القائمة
Convert Markdown with Mermaid diagrams and SVG illustrations to professional Word documents
يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.
اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.
npx skills add https://github.com/fabioc-aloha/Alex_ACT_Edition_v2 --skill md-to-wordيبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
استنادا إلى تصنيف SOC المهني
عرض SKILL.md
| type | skill |
| lifecycle | stable |
| name | md-to-word |
| description | Convert Markdown with Mermaid diagrams and SVG illustrations to professional Word documents |
| tier | standard |
| applyTo | **/*docx*,**/*word*,**/*md-to-word*,**/*export* |
| muscle | .github/muscles/md-to-word.cjs |
| inheritance | inheritable |
| currency | 2026-05-18T00:00:00.000Z |
| lastReviewed | 2026-05-18T00:00:00.000Z |
One command to professional Word documents — diagrams, tables, and formatting done right on first attempt.
Convert any Markdown document into polished Word (.docx) files ready for stakeholders, executives, and external audiences. Supports all standard Markdown formatting, Mermaid diagrams (auto-converted to PNG), and SVG illustrations (auto-embedded).
| Without This Skill | With This Skill |
|---|---|
| Mermaid diagrams missing or broken | Auto-rendered to high-res PNG, optimally sized |
| SVG images not displaying | Auto-converted to PNG with proper dimensions |
| Tables plain and unprofessional | Microsoft-branded headers, borders, zebra striping |
| Tables split mid-row across pages | Smart pagination keeps rows intact |
| Images overflow page boundaries | 90% page coverage constraint ensures fit |
| Bullet lists merge into paragraphs | Preprocessor fixes spacing automatically |
| Code blocks lose formatting | Consolas font, gray background, proper borders |
| Links plain text | Blue underlined hyperlinks |
| Headings inconsistent | Branded colors, proper hierarchy |
Markdown (.md) → md-to-word.cjs → Word (.docx) → Final PDF
↓ ↓ ↓ ↓
Source Automation Manual polish Distribution
(your docs) (this skill) (page breaks, (File > Save As)
headers/footers)
md-to-word.cjs — produces a complete, styled document| Feature | Support | Notes |
|---|---|---|
| Headings (H1-H6) | ✅ Full | Branded colors, proper spacing |
| Bold/Italic/Strikethrough |
| ✅ Full |
**bold**, *italic*, ~~strike~~ |
| Bullet lists | ✅ Full | Nested supported |
| Numbered lists | ✅ Full | Auto-numbered |
| Task lists | ✅ Full | - [ ] / - [x] converted |
| Tables | ✅ Full | Professional styling |
| Code blocks | ✅ Full | Syntax highlighting preserved |
| Inline code | ✅ Full | Monospace with background |
| Links | ✅ Full | Blue underlined |
| Images (PNG/JPG) | ✅ Full | Centered, auto-sized |
| SVG images | ✅ Auto-convert | Rendered to PNG |
| Mermaid diagrams | ✅ Auto-convert | Rendered to PNG |
| Blockquotes | ✅ Full | Gray left border |
| Horizontal rules | ✅ Full | Light gray line |
| Footnotes | ✅ Pandoc | Via pandoc extension |
| YAML frontmatter | ✅ Strip | --strip-frontmatter option |
All Mermaid diagram types are supported:
| Diagram Type | Detection | Sizing Strategy |
|---|---|---|
| Flowchart LR | flowchart lr | Width priority (6.5") |
| Flowchart TB | flowchart tb | Height priority (3.6") |
| Sequence | sequenceDiagram | Width priority |
| Gantt | gantt | Width priority (wide) |
| Class | classDiagram | Auto |
| ER | erDiagram | Auto |
| State | stateDiagram | Auto |
| Pie | pie | Smaller width |
| Mindmap | mindmap | Width priority |
| Timeline | timeline | Width priority |
Diagrams are rendered at 4x scale (4800px width) for crisp printing, then sized to fit within page bounds.
# From your project root
node .github/muscles/md-to-word.cjs docs/spec.md
# With custom output name
node .github/muscles/md-to-word.cjs README.md output.docx
# Keep intermediate files for debugging
node .github/muscles/md-to-word.cjs docs/plan.md --keep-temp
| Tool | Install (macOS) | Install (Windows) | Purpose |
|---|---|---|---|
| Node.js 18+ | brew install node | winget install OpenJS.NodeJS.LTS | Script runtime |
| pandoc | brew install pandoc | winget install JohnMacFarlane.Pandoc | Markdown to Word |
| mermaid-cli | npm install -g @mermaid-js/mermaid-cli | same | Mermaid to PNG |
| jszip | (bundled with extension) | same | OOXML post-processing |
| svgexport | npm install -g svgexport | same | SVG to PNG (optional) |
macOS
brew install pandoc
npm install -g @mermaid-js/mermaid-cli svgexport
Windows
winget install JohnMacFarlane.Pandoc
npm install -g @mermaid-js/mermaid-cli svgexport
| Option | Default | Description |
|---|---|---|
--toc | off | Generate Table of Contents. A [toc] marker in the source is stripped but does not auto-enable TOC (since v5.5.0). When the marker is found without --toc, a warning is logged so the heir can either pass --toc explicitly or remove the marker. |
--cover | off | Generate cover page from H1 + date |
--style PRESET | professional | Style preset (see below) |
--page-size SIZE | letter | Page size: letter, a4, 6x9 |
--reference-doc PATH | — | Custom Word template (.dotx) |
--images-dir DIR | images | Directory for generated PNG files |
--embed-images | off | Embed local images as base64 |
--strip-frontmatter | off | Remove YAML frontmatter |
--no-format-tables | off | Skip table styling (faster) |
--keep-temp | off | Keep temporary files for debugging |
--watch | off | Auto-rebuild on source change |
--recursive | off | Process all .md files in directory |
--dry-run | off | Validate only, no output |
--debug | off | Save preprocessed markdown |
| Preset | Body Font | Heading Style | Use Case |
|---|---|---|---|
| professional | Segoe UI 10.5pt | Microsoft blue (#0078D4) | Business documents, specs, reports |
| academic | Times New Roman 12pt | Black, double-spaced | Dissertations, papers, theses |
| course | Calibri 11pt | Virginia Tech burgundy | Course materials, syllabi |
| creative | Georgia 11pt | Slate blue | Blog posts, narratives |
# Academic paper with TOC
node md-to-word.cjs thesis.md --style academic --toc
# Professional report with cover
node md-to-word.cjs quarterly-report.md --style professional --cover --toc
SVG files are automatically detected and converted to PNG for Word compatibility:
<!-- This SVG reference in your Markdown... -->
<!-- ...becomes this embedded PNG in Word -->
{width=5.8in}
Requirements: svgexport (npm install -g svgexport)
Best practices for SVG sources:
The script automatically fits images to page bounds. The constraints are codified
in md-to-word.cjs:
Page: 8.5" × 11" (Letter)
Margins: 1" each side
Usable area: 6.5" × 9.0"
MAX_IMAGE_WIDTH_RATIO = 0.90 → max width ≈ 5.85"
MAX_IMAGE_HEIGHT_RATIO = 0.60 → max height ≈ 5.40"
These ratios apply width-priority for landscape/wide diagrams (LR flowcharts, gantts, sequence diagrams) and height-priority for portrait/tall diagrams (TB/TD flowcharts with multiple subgraphs). The algorithm picks the more restrictive constraint so the image fits in both dimensions.
When a Mermaid block has no classDef, no %%{init}%% directive, and no
explicit theme variables, the converter injects a default pastel palette
(GitHub-style soft colors with dark text) before rendering. This gives WYSIWYG
fidelity to authors who don't styled-by-design every diagram.
| Diagram type | Honors classDef? | Color path |
|---|---|---|
flowchart / graph | Yes | classDef (preferred) or injected init |
classDiagram | Partial | classDef or injected init |
sequenceDiagram | No | themeVariables only (e.g. actorBkg, noteBkgColor) |
stateDiagram-v2 | No | themeVariables only (primaryColor, mainBkg, labelBoxBkgColor) |
erDiagram | No | themeVariables only |
Without diagram-type-aware injection, sequence and state diagrams would render
as flat neutral nodes regardless of any classDef the author wrote.
flowchart / graph / classDiagram with classDef → respected, no
injection (author wins)flowchart / graph without classDef → palette injected + lint nudgesequenceDiagram / stateDiagram-v2 without %%{init}%% or explicit
actorBkg / primaryColor → palette injected (only path to colors)%%{init}%% already present → respected, no injectionPass --no-default-palette to disable injection. Diagrams without classDef or
explicit theme will then render with mermaid's default neutral theme, and a
warning is emitted per affected diagram.
During preprocessing the converter emits 💡 nudges for unstyled flowcharts
("inject default pastel palette") and ⚠️ warnings when --no-default-palette
is set on diagrams that would have rendered flat.
All tables receive professional OOXML styling (tightened in v5.5.0 for denser, more reference-document-style tables):
| Element | Style |
|---|---|
| Header row | Microsoft blue (#0078D4), white text, bold 9pt |
| Even data rows | Light gray (#F0F0F0) |
| Odd data rows | White (#FFFFFF) |
| Data cell font | 8.5pt black |
| Borders | Gray outer (#666666), light inner (#AAAAAA) |
| Cell padding | 1pt top/bottom, 3pt left/right |
| Pagination | cantSplit + keepWithNext (no orphan headers) |
| Repeat headers | Header row repeats on each page for long tables |
Centered page numbers in the footer, gray text (9pt).
Paragraphs starting with "Table N" or "Figure N":
| Issue | Cause | Fix |
|---|---|---|
| "mmdc not found" | mermaid-cli not installed | npm install -g @mermaid-js/mermaid-cli |
| "pandoc not found" | pandoc not in PATH | winget install JohnMacFarlane.Pandoc (restart terminal) |
| "svgexport not found" | svgexport not installed | npm install -g svgexport |
| Tables not styled | jszip not available | Set NODE_PATH to extension node_modules |
| Diagrams too small | Outdated script | Update to v5.3.0+ |
| Images overflow | Complex diagram | Use --debug and check PNG dimensions |
| SVG not converting | Missing svgexport | Install or use PNG source |
| Document corrupt | Incomplete write | Check disk space, re-run |
node md-to-word.cjs doc.md --debug --keep-temp
# Check _debug_combined.md for preprocessed content
# Check images/ folder for generated PNGs
macOS ships textutil which can convert HTML to DOCX natively:
# Convert markdown to HTML first, then HTML to DOCX
npx marked document.md -o document.html
textutil -convert docx document.html -output document.docx
| Feature | Pandoc (primary) | textutil (fallback) |
|---|---|---|
| Table styling | Full (via jszip post-processing) | Basic |
| Mermaid diagrams | Supported (pre-rendered PNG) | Must be pre-rendered |
| Heading styles | Mapped to Word styles | Basic HTML mapping |
| Cross-references | Supported | Not supported |
| Install | brew install pandoc | Built-in (macOS only) |
Limitations: textutil needs HTML input (not raw Markdown), produces simpler formatting, and doesn't support the table styling or image sizing that md-to-word.cjs provides. Use only when Pandoc is unavailable and a quick conversion is needed.
# Windows PowerShell
Get-ChildItem docs/*.md | ForEach-Object {
node .github/muscles/md-to-word.cjs $_.FullName --style professional
}
# macOS/Linux
for f in docs/*.md; do
node .github/muscles/md-to-word.cjs "$f" --style professional
done
# All .md files in docs/ and subdirectories
node .github/muscles/md-to-word.cjs docs --recursive --style professional
# Auto-rebuild when source changes
node .github/muscles/md-to-word.cjs spec.md --watch
# Generate Word docs as build artifacts
- name: Generate Word Documents
run: |
npm install -g @mermaid-js/mermaid-cli svgexport
node .github/muscles/md-to-word.cjs docs/spec.md --toc --cover
- name: Upload artifacts
uses: actions/upload-artifact@v4
with:
name: word-documents
path: docs/*.docx
{
"scripts": {
"docs:word": "node .github/muscles/md-to-word.cjs docs/README.md --style professional --toc"
}
}
.github/muscles/md-to-word.cjs to your project.github/muscles/shared/ (markdown-preprocessor, mermaid-pipeline)npm install -g @mermaid-js/mermaid-cli svgexportnode .github/muscles/md-to-word.cjs your-doc.md| Version | Changes |
|---|---|
| 5.5.0 | Tighter table styling (header 10pt→9pt, data 9pt→8.5pt, cell margins 2pt/4pt → 1pt/3pt). [toc] marker in source now strips the line but does not auto-enable TOC — warning logged instead, requires explicit --toc to generate. Coverage smoke test corpus added at docs/testing/md-to-word-coverage.md. |
| 5.4.0 | Diagram-type-aware Mermaid palette injection (sequence/state get themeVariables, flowcharts respect classDef), --no-default-palette opt-out, lint warnings for unstyled diagrams, sizing constants documented |
| 5.3.0 | Style presets (professional, academic, course, creative), --cover, --toc |
| 5.0.0 | SVG auto-conversion via svgexport, watch mode, recursive processing |
| 4.0.0 | OOXML post-processing: page numbers, hyperlinks, code block styling |
| 3.0.0 | Markdown preprocessing, heading colors, caption formatting |
| 2.1.0 | Table pagination (cantSplit, keepWithNext) prevents orphan headers |
| 2.0.0 | 90% H+V coverage, actual PNG dimension reading |
| 1.0.0 | Initial: pandoc + mermaid + table formatting |
| Condition | Verdict | Action |
|---|---|---|
| All headings use correct Word styles (Heading 1-6) | Accept | Verify TOC generates from styles |
| Headings are bold plain text instead of styled | Reject | Check pandoc heading-style mapping |
| Tables render with borders and header row formatting | Accept | Spot-check alignment |
| Tables overflow page width or lose column alignment | Reject | Adjust column widths or split wide tables |
| Images embedded at correct resolution | Accept | Verify no placeholder boxes |
Images missing or show [image] placeholder | Reject | Check image paths resolve; pandoc --resource-path |
| Mermaid diagrams converted to PNG and embedded | Accept | Verify labels readable at print size |
| Mermaid diagrams missing entirely | Reject | Pre-render with mermaid-cli before pandoc |
| Code blocks use monospace font with syntax coloring | Accept | Verify long lines don't overflow |
| Code blocks use body font or lose indentation | Warning | Check pandoc --highlight-style setting |
| Page breaks at expected section boundaries | Accept | Required for multi-section documents |
| Headers/footers match brand template | Accept | Verify reference.docx applied correctly |
| File opens without macro warnings | Accept | Required — no macros in output |
| File size >10MB for text-only document | Warning | Check for uncompressed embedded images |
| Skill | Relationship |
|---|---|
| markdown-mermaid | Mermaid syntax and ATACCU compliance |
| lint-clean-markdown | Pre-flight the source — pass clean Markdown in |
| markdown-sanitization-chain | Sanitize user-supplied Markdown before conversion |
| markdown-mermaid § Mode Fragility | Why we default to flowchart mode |
| svg-graphics | Vector graphics creation |
| brand-asset-management | Visual identity for headers/footers |
| pptx-generation | Similar workflow for PowerPoint output |
| md-to-html | HTML output with same preprocessing |
| md-scaffold | Templates for clean Markdown structure |
| book-publishing | Pandoc PDF for print publishing |