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.
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.
@mermaid-js/mermaid-cli.--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:
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:
$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.
.docx extension.With mmdc on PATH:
python scripts/markdown_to_word.py input.md --output output.docx
Using a workspace-local CLI on Windows:
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:
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 to a new output path. It includes English and Japanese labels, multiple diagrams, and a tall diagram.
title and descr) includes the section heading or Mermaid accTitle/accDescr plus the diagram type.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.title becomes the document title; other frontmatter fields are removed from the body. This is not a full YAML metadata parser.Run the test suite from the skill directory:
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:
$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:
foreignObject remains in the sample's SVGs.For contribution scope, evaluation cases, and a draft submission description, see references/publication.md. That file is maintainer guidance, not permission to publish.
mmdc.cmd needs Windows command handling; pass its path with --mermaid-cli rather than rewriting the script.