К основному содержанию
скилл CX Codex официальный · GitHub

markdown-to-word-mermaid — скилл для GitHub Copilot: экспорт в DOCX

Скилл markdown-to-word-mermaid для GitHub Copilot превращает Markdown с диаграммами Mermaid в документ Word. Диаграммы сохраняются в SVG с PNG-резервом, а крупные изображения размещаются с учётом страниц.

MIT ★ 41 430 обновлён 2026-10-23

Установить в GitHub Copilot · GitHub CLI Все способы и платформы ↓
gh skill install github/awesome-copilot skills/markdown-to-word-mermaid
Открыть на GitHub

Что делает markdown-to-word-mermaid

Скилл запускает конвертер, который переносит Markdown в DOCX и рендерит блоки Mermaid в SVG и PNG. Заголовки, списки, таблицы и блоки кода становятся содержимым Word; обычные ссылки на изображения остаются текстом с альтернативным описанием и путём или URL.

Для работы нужны Python 3.10+ с пакетами из scripts/requirements.txt, Node.js, совместимый с выбранной версией Mermaid CLI, сам @mermaid-js/mermaid-cli, локальный браузер для Puppeteer и установленный шрифт для символов документа. Шрифты в DOCX не встраиваются, а обычные изображения из Markdown не добавляются в файл.

Скилл не перезаписывает существующий документ: для вывода нужно указать новый путь. Диаграммы не становятся редактируемыми объектами Office, а результат отображения зависит от версии Word и подстановки шрифтов.

Какие задачи решает

  • экспортировать Markdown с Mermaid в DOCX
  • сохранить диаграммы векторными для просмотра и печати
  • разместить высокую диаграмму с учётом разрывов страниц
  • перенести таблицы, списки и блоки кода в Word

Примеры запросов агенту

  • Преобразуй design.md в design.docx, сохранив диаграммы Mermaid.
  • Экспортируй runbook.md в Word и размести высокую диаграмму целиком на странице.
  • Собери DOCX из report.md со шрифтом Noto Sans JP.

Как установить markdown-to-word-mermaid

1GitHub CLI

gh skill install github/awesome-copilot skills/markdown-to-word-mermaid

2Вручную: положить файлы

.github/skills/markdown-to-word-mermaid/SKILL.md

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о markdown-to-word-mermaid

Как установить markdown-to-word-mermaid в GitHub Copilot?

Выполни gh skill install github/awesome-copilot skills/markdown-to-word-mermaid. Файл скилла находится по пути .github/skills/markdown-to-word-mermaid/SKILL.md.

Что делает markdown-to-word-mermaid?

Конвертирует Markdown в DOCX и добавляет диаграммы Mermaid как SVG с PNG-резервом. Диаграммы не становятся редактируемыми фигурами Word.

Что нужно для работы markdown-to-word-mermaid?

Нужны Python 3.10+ и пакеты из scripts/requirements.txt, Node.js, совместимый с Mermaid CLI, пакет @mermaid-js/mermaid-cli, локальный браузер для Puppeteer и установленный шрифт, покрывающий символы документа.

Исходный текст

SKILL.md · MIT
---
name: markdown-to-word-mermaid
description: 'Export Markdown containing Mermaid code fences to Word (.docx) with embedded SVG diagrams and PNG fallbacks. Use when diagram sharpness, Office-compatible labels, or page-aware placement matters. Not for Word-to-Markdown conversion, editable Office shapes, or general slide creation.'
license: MIT
argument-hint: 'Markdown input file and optional DOCX output path'
user-invocable: true
---

# Markdown to Word with Mermaid

Export technical documents without manually replacing Mermaid fences with screenshots. The bundled converter renders each diagram locally, embeds the SVG through Office OOXML relationships, and retains a 3x PNG fallback. Word is not required to generate the file; an SVG-capable Word version is needed to inspect vector rendering.

## When to use

- A design document, runbook, or report contains Mermaid code fences and must be delivered as DOCX.
- Diagram labels must remain sharp when zoomed or printed.
- A tall diagram needs page-aware placement rather than being split across pages.

For general Markdown-to-DOCX conversion with existing PNG images, a general converter such as `md-to-docx` may be simpler. This skill focuses on rendering and packaging Mermaid diagrams. SVG embedding does not create editable Word shapes, connectors, or text boxes.

## Requirements and setup

- Python 3.10+ and the packages in [scripts/requirements.txt](scripts/requirements.txt).
- Node.js compatible with the chosen Mermaid CLI release, plus `@mermaid-js/mermaid-cli`.
- A local browser usable by Puppeteer and an installed font covering the document's characters.
- Default font: Noto Sans JP. Use `--font-family` to select another installed family.

Resolve paths relative to this skill's installation directory, not an assumed repository name. The examples below run from the skill directory. Use the user's selected Python environment (`python`, `python3`, or its absolute path).

Before installing dependencies, confirm the environment and obtain permission if required. Reuse an existing Mermaid CLI when available. Otherwise install it into a user-approved local tools directory, not globally:

```sh
python -m pip install -r scripts/requirements.txt
npm install --prefix ./run/mermaid-cli @mermaid-js/mermaid-cli
```

The local executable is `./run/mermaid-cli/node_modules/.bin/mmdc` on POSIX and `./run/mermaid-cli/node_modules/.bin/mmdc.cmd` on Windows. Keep installed dependencies out of the submitted skill package. Lock the selected dependency versions in the consuming project for reproducible installations.

On Windows the converter detects standard Chrome and Edge paths. For another browser location, set `MERMAID_BROWSER_PATH` to its absolute executable path:

```powershell
$env:MERMAID_BROWSER_PATH = "C:\Program Files\Google\Chrome\Application\chrome.exe"
```

On POSIX, use `export MERMAID_BROWSER_PATH=/absolute/path/to/browser`, or use Puppeteer's installed browser. Do not disable the browser sandbox just to make a conversion pass.

## Workflow

1. Confirm the input Markdown file, output destination, and font. If no destination is provided, use the input path with a `.docx` extension.
2. Check that the output does not exist. Never delete or overwrite an existing document; ask for a different destination.
3. Run [scripts/markdown_to_word.py](scripts/markdown_to_word.py). Preserve the user's diagram source and meaning. Do not silently repair invalid Mermaid.
4. Check the generated package and, when Word is available, inspect the document visually. Report package checks and visual checks separately.

With `mmdc` on PATH:

```sh
python scripts/markdown_to_word.py input.md --output output.docx
```

Using a workspace-local CLI on Windows:

```powershell
python scripts/markdown_to_word.py input.md --output output.docx --mermaid-cli ./run/mermaid-cli/node_modules/.bin/mmdc.cmd
```

Selecting an installed font:

```sh
python scripts/markdown_to_word.py input.md --output output.docx --font-family "Noto Sans JP" --timeout 120
```

For a reproducible example, convert [assets/example.md](assets/example.md) to a new output path. It includes English and Japanese labels, multiple diagrams, and a tall diagram.

## Conversion behavior

- Headings, paragraphs, emphasis, lists (preserving ordered list start numbers and separate list boundaries), blockquotes, tables, and code blocks become Word content.
- Each Mermaid fence renders to SVG and a 3x PNG with a per-command timeout (default: 120 seconds). Office SVG extensions reference the SVG; the normal image reference retains the PNG fallback, and drawing metadata (`title` and `descr`) includes the section heading or Mermaid `accTitle`/`accDescr` plus the diagram type.
- Output DOCX files are staged and SVG-injected inside a temporary directory before moving to the destination path so failed runs never leave partial files behind.
- The selected font is applied to Word paragraph styles and Mermaid's font configuration. Code runs use Consolas. Fonts are not embedded; unavailable fonts may be substituted.
- `htmlLabels: false` is set globally and for flowcharts to avoid HTML `foreignObject` labels that Office may not display. Check actual SVG output for unsupported constructs.
- Diagrams are centered, keep their aspect ratio, and use a non-splitting paragraph. Diagrams occupying at least 70% of the page body height start on a new page. Oversized diagrams are scaled to the page body height. Large diagrams generate a readability warning.
- A simple single-line frontmatter `title` becomes the document title; other frontmatter fields are removed from the body. This is not a full YAML metadata parser.
- Ordinary Markdown image links remain alt text and a source path or URL; they are not embedded. Raw HTML is reduced to text, not executed.

## Stop conditions and limitations

- Missing input, wrong extensions, an existing output, missing CLI, invalid Mermaid, rendering failure, or unusable SVG dimensions stop the conversion with an error.
- The converter does not call an external rendering service or a separate AI API. Dependency installation and browser execution are not an offline sandbox. Review untrusted diagram content, including external resources, before rendering it.
- Diagrams are not semantically editable Office objects. Word rendering, font substitution, and final pagination depend on the viewer and must be checked there.
- A successfully created DOCX is not proof that every diagram label is readable. Split large diagrams in the source only with the user's approval.

## Verification

Run the test suite from the skill directory:

```sh
python -m unittest discover -s tests -v
```

The ordinary suite mocks Mermaid rendering. To run the real-renderer test as well, set `MERMAID_CLI` to the CLI executable's absolute path, then run the command again. On Windows PowerShell:

```powershell
$env:MERMAID_CLI = (Join-Path $env:APPDATA "npm\mmdc.cmd")
python -m unittest discover -s tests -v
```

That test renders the bundled sample and checks the resulting DOCX's SVG references, PNG fallbacks, labels, and drawing dimensions. It does not automate Word visual inspection.

Before reporting completion:

- Count Mermaid fences and verify the same number of SVG parts and SVG image references in the DOCX.
- Confirm PNG fallback references exist and no label `foreignObject` remains in the sample's SVGs.
- In Word, inspect node names, branch labels, font, diagram placement, and page boundaries; check zoomed or printed output when sharpness matters.
- If Word or the actual renderer was unavailable, state which checks were not performed.

For contribution scope, evaluation cases, and a draft submission description, see [references/publication.md](references/publication.md). That file is maintainer guidance, not permission to publish.
## Gotchas

- `mmdc.cmd` needs Windows command handling; pass its path with `--mermaid-cli` rather than rewriting the script.
- A missing font can affect both PNG rendering and SVG display. Use a family installed on the rendering and viewing machines.
- Keep the SVG and PNG paired. Replacing SVG with a screenshot defeats the vector-preserving workflow.
- Package validation, renderer tests, agent-selection evaluation, and human visual acceptance are different checks.

© github · MIT · github/awesome-copilot

Похожие скиллы

Все скиллы по теме «Тексты и документация» →
Word to Markdown benbalter MCP-сервер Word to Markdown для Claude Code преобразует DOCX в Markdown, сохраняя таблицы, формулы в LaTeX и сноски. Переносит офисные документы в репозиторий. CX Codex +1 ★ 274звёзд репо aigroup-mdtoword-mcp jackdark425 MCP-сервер aigroup-mdtoword-mcp превращает Markdown в готовый .docx с таблицами, формулами, изображениями и диаграммами Mermaid. Работает локально через протокол MCP. CX Codex +1 ★ 14звёзд репо markdown-mermaid-writing K-Dense-AI Скилл markdown-mermaid-writing пишет научную документацию в Markdown и рисует структурные диаграммы Mermaid: схемы процессов, связей, таймлайны. Полезен, когда отчёт или README должны лежать в git как текст. CX Codex +1 2 300установок word-document PracticalSwan Скилл word-document для чтения, создания и правки документов Word: таблицы, сноски, комментарии, стили и конвертация в PDF. CX Codex +1 797установок Word AI flyfish-dev MCP-сервер Word AI для Claude Code точечно редактирует DOCX, сохраняя разметку, стили и таблицы. Через агента он обновляет отчёты и спецификации без повреждения структуры. CX Codex +1 ★ 10звёзд репо che-word-mcp PsychQuant MCP-сервер che-word-mcp на Swift для Claude Code и Codex: читает, наполняет и рецензирует DOCX через Office Open XML без Microsoft Word и сторонних сред выполнения. CX Codex +1 ★ 7звёзд репо

Из того же набора993

Весь набор →
pr-artifact-explorer Скилл pr-artifact-explorer для GitHub Copilot открывает GitHub PR, issues, запуски workflow, Actions-артефакты и веб-превью в общей панели. Он включается по запросу показать или изучить эти материалы. CX Codex +1 ★ 41 430звёзд репо ponder Скилл ponder для GitHub Copilot запускает цикл повторных проходов оценки проекта, пока выводы модели не перестанут меняться. Проверяет полное покрытие всех модулей без пропуска файлов. CX Codex +1 ★ 41 430звёзд репо openapi-to-application-java-spring-boot Скилл openapi-to-application-java-spring-boot для GitHub Copilot превращает спецификацию OpenAPI в основу приложения на Spring Boot. Он включается, когда нужно создать или доработать Java API по файлу OpenAPI или Swagger. CX Codex +1 ★ 41 430звёзд репо on-device-delegate Скилл on-device-delegate для GitHub Copilot передаёт объёмное чтение файлов локальному агенту. Основная сессия экономит контекст облачной модели при разборе логов или поиске фактов. CX Codex +1 ★ 41 430звёзд репо logicapps-custom-code-net10-migration Скилл logicapps-custom-code-net10-migration для GitHub Copilot переводит проекты кастомного кода Azure Logic Apps Standard с .NET 8 на .NET 10. Настраивает конфигурацию проектов, сборку и локальную отладку в VS Code. CX Codex +1 ★ 41 430звёзд репо lightweight-charts-react-components Скилл lightweight-charts-react-components для GitHub Copilot помогает добавлять и чинить финансовые графики на React с lightweight-charts. Включается по запросу о TradingView-графиках, пакетах lightweight-charts или их возможностях. CX Codex +1 ★ 41 430звёзд репо globestudio Генерирует точечные карты мира и трёхмерные анимированные глобусы через веб-сервис Globestudio. Создаёт ссылки с JSON-конфигурацией и код для встраивания на сайт. CX Codex +1 ★ 41 430звёзд репо foundry-agentic-loop Скилл foundry-agentic-loop для GitHub Copilot координирует создание агентных решений на Microsoft Foundry и Azure. Запускает прототипирование, разработку по спецификации или улучшение скилла по результатам прошлых запусков. CX Codex +1 ★ 41 430звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой