Confluence Mermaid Converter

Конвертирует mermaid-блоки кода в страницах Confluence в формат плагина Mermaid for Confluence.

Проблема

Когда mermaid-диаграммы хранятся в Confluence как блоки кода:

{type: "codeBlock", attrs: {language: "mermaid"}, content: [...]}

Они отображаются как сырой код вместо отрендеренных диаграмм. Этот инструмент конвертирует их в формат плагина Mermaid for Confluence:

{type: "extension", attrs: {extensionKey: "mermaid", ...}}

Файлы

Файл	Описание
`convert_confluence_mermaid.py`	Основной скрипт конвертации
`update_confluence_page.sh`	Полный рабочий процесс (получение → конвертация → обновление)
`fetch_page_body.py`	Утилита для получения тела страницы в формате JSON

Требования

Python 3.6+
curl (для shell-скрипта)
Atlassian API token (создать здесь)

Использование

Вариант 1: Полностью автоматизированный процесс

bash

./update_confluence_page.sh <instance> <page_id> <email> <api_token>

# Пример:
./update_confluence_page.sh id-ware.atlassian.net 1413480449 user@example.com ATATT3xxxxxxxxxxx

Вариант 2: Пошаговое выполнение

Получить тело страницы:

bash

python3 fetch_page_body.py id-ware.atlassian.net 1413480449 user@example.com ATATT3xxx > original.json

Конвертировать mermaid-блоки:
python3 convert_confluence_mermaid.py original.json converted.json
Обновить страницу вручную через Confluence REST API или скопировав содержимое converted.json.

Вариант 3: Передача через stdin

cat page_body.json | python3 convert_confluence_mermaid.py - converted.json

Принцип работы

Скрипт выполняет следующие шаги:

Разбирает JSON в формате ADF (Atlassian Document Format)
Находит все узлы codeBlock с language: "mermaid"
Конвертирует каждый в узел extension со следующими параметрами:
- extensionType: "com.atlassian.confluence.macro.core"
- extensionKey: "mermaid"
- __bodyContent с определением диаграммы
- Уникальные идентификаторы для fileName, macroId и localId
Выводит конвертированный ADF JSON

Формат расширения

Плагин Mermaid for Confluence ожидает следующую структуру:

json

{
  "type": "extension",
  "attrs": {
    "layout": "default",
    "extensionType": "com.atlassian.confluence.macro.core",
    "extensionKey": "mermaid",
    "parameters": {
      "macroParams": {
        "fileName": {"value": "mermaid_1735496100001"},
        "theme": {"value": "default"},
        "version": {"value": "2"},
        "__bodyContent": {"value": "{\"diagramDefinition\":\"graph TD\\n    A-->B\"}"}
      },
      "macroMetadata": {
        "macroId": {"value": "uuid-here"},
        "schemaVersion": {"value": "1"},
        "placeholder": [{"type": "icon", "data": {"url": "..."}}],
        "title": "Mermaid Integration for Confluence"
      }
    },
    "localId": "uuid-here"
  }
}

Справочник по API

Confluence REST API v2

Получить страницу с телом в формате ADF:

GET /wiki/api/v2/pages/{page_id}?body-format=atlas_doc_format

Обновить страницу:

PUT /wiki/api/v2/pages/{page_id}
Content-Type: application/json

{
  "id": "page_id",
  "status": "current", 
  "title": "Page Title",
  "body": {
    "representation": "atlas_doc_format",
    "value": "escaped-json-string"
  },
  "version": {
    "number": current_version + 1,
    "message": "Update message"
  }
}

Устранение неполадок

«Invalid JSON input»

Убедитесь, что передаёте JSON тела ADF, а не полный ответ API.

«Permission denied»

Проверьте, что ваш API token имеет права на запись для данной страницы.

Диаграммы не отображаются

Убедитесь, что плагин Mermaid for Confluence установлен и включён в вашем экземпляре Confluence.

Лицензия

MIT

Mermaid для Confluence

Установка

README