Markdown to Word (.docx) Converter

Convert Markdown files to formatted Word (.docx) documents with automatic template style detection. Use this skill whenever the user mentions converting Mark...

Security Scan

The skill's code, instructions, and requested dependencies are consistent with a Markdown→.docx converter; nothing in the provided files indicates hidden exfiltration or unrelated credential access, though it does read local files and invokes external tooling (pip/npm/Chrome/LibreOffice/mmdc).

Purpose & Capability

Name/description match the included script and instructions. Required tools (python-docx, mermaid-cli, Chrome/Chromium, LibreOffice/textutil) are appropriate for parsing Markdown, rendering Mermaid to PNG, and handling .doc/.docx templates. No unrelated environment variables, binaries, or config paths are requested.

Instruction Scope

SKILL.md instructs the agent to identify user-specified input files and check common template locations (e.g., docs/, templates/) and to install dependencies with pip/npm if missing. These actions are necessary for conversion but do require the agent to read local files and potentially run package installs and external binaries. There are no instructions to transmit data to external endpoints in the provided content.

Install Mechanism

The skill is instruction-only (no install spec) but bundles a Python script. Dependencies are installed via pip and npm (global mermaid-cli). Using global npm/pip installs or relying on system Chrome/LibreOffice is expected here, but installing packages globally has side effects and requires network access and appropriate privileges.

Credentials

No environment variables, credentials, or config paths are required. The script inspects local filesystem paths for templates and browser binaries, which is coherent with its purpose.

Persistence & Privilege

Skill does not request always:true and does not declare persistent elevated privileges. It runs as a user-invocable skill and may be invoked autonomously (platform default), which is expected for an assistant skill of this type.

Assessment

This skill appears to do what it says: convert Markdown to .docx using a bundled Python script and external tools. Before installing or running it, consider: 1) Review the full script locally (especially the truncated part) to confirm there are no unexpected network calls or file accesses beyond templates and the input file. 2) The SKILL will read files you point it at and search common template directories — do not point it at directories containing secrets. 3) It asks to install dependencies via pip/npm (the README and SKILL.md suggest running npm install -g @mermaid-js/mermaid-cli), which requires network access and may install global binaries; prefer installing into a virtualenv or installing mermaid-cli locally to avoid global side effects. 4) It invokes system binaries (Chrome/Chromium, textutil, libreoffice, mmdc) via subprocess — ensure those are trusted on your machine. 5) If you want extra safety, run conversions in a sandbox/container or on a machine without sensitive files. If you want, provide the remaining portion of the script for a deeper review of subprocess calls and any network activity.

Convert Markdown files to professionally formatted Word documents, with automatic template style extraction and Mermaid diagram rendering.

How It Works

The bundled script (scripts/md_to_docx.py) handles the entire conversion:

1. Parse Markdown into structured blocks (headings, body, lists, tables, code, quotes)
2. Extract styles from an optional Word template (.doc or .docx) — font, size, alignment, spacing
3. Apply formatting to each block, preserving inline Markdown (bold, italic, code, strikethrough)
4. Render Mermaid diagrams to PNG via mmdc (mermaid-cli) and embed them as images
5. Output a ready-to-use .docx file

Dependencies

The script requires:

• python-docx: pip install python-docx
• mmdc (for Mermaid rendering): npm install -g @mermaid-js/mermaid-cli
• Chrome or Chromium: must be installed locally (auto-detected on macOS/Windows/Linux)

On macOS, .doc templates are converted via the built-in textutil. On Linux, LibreOffice is used as fallback.

Usage

Basic conversion (default Chinese typesetting)

python3 scripts/md_to_docx.py input.md -o output.docx

With template (auto-extract formatting)

python3 scripts/md_to_docx.py input.md -o output.docx -t template.doc

When Invoked as a Skill

When the user asks to convert a Markdown file to Word:

1. Identify the input file — the user will typically specify a .md file path
2. Check for a template — ask if they have a .doc/.docx template, or check if one exists in common locations (docs/, templates/)
3. Ensure dependencies are installed:

   pip3 install python-docx
   npm list -g @mermaid-js/mermaid-cli 2>/dev/null || npm install -g @mermaid-js/mermaid-cli
   

4. Run the script from the skill's scripts/ directory:

   python3 <skill-path>/scripts/md_to_docx.py <input.md> -o <output.docx> [-t <template.doc>]
   

5. Report results — tell the user the output path and whether all Mermaid diagrams rendered successfully

Template Format Detection

When a template is provided, the script analyzes it automatically:

• Title levels are identified by font size and alignment (largest centered = chapter title, etc.)
• Body text is identified by paragraphs with first-line indentation
• Page setup (margins, paper size) is copied from the template
• Chinese font pairing is preserved (e.g., Times New Roman ↔ 宋体, Arial ↔ 黑体)

If no template is provided, these defaults are used (Chinese publishing standard):

Element	Font	Size	Alignment
Chapter title (h1)	黑体	18pt	Center
Section title (h2)	黑体	16pt	Center
Subsection (h3)	黑体	14pt	Left
Body text	宋体	10.5pt (五号)	Justify, 2-char indent
Code	Consolas	9pt	Left
Quote	楷体	10.5pt	Left indent, italic

Supported Markdown Features

• Headings: h1–h6 (h1 = chapter, h2 = section, h3 = subsection, h4+ = sub-subsection)
• Body text with inline: bold, italic, code, strikethrough, bold italic
• Bullet lists (- or *) and ordered lists (1.)
• Tables with header detection
• Code blocks with language label
• Mermaid diagrams rendered to embedded PNG images
• Block quotes and horizontal rules

Mermaid Diagram Handling

Mermaid code blocks are rendered to PNG via mmdc using the local Chrome browser. If rendering fails (e.g., Chrome not found, syntax error), the diagram falls back to a code block display.

Common Mermaid compatibility fixes are applied automatically:

• subgraph names containing colons are quoted
• Parentheses in subgraph names are escaped

Cross-Platform Notes

• macOS: Chrome auto-detected at /Applications/Google Chrome.app/...
• Windows: Checks Program Files and LocalAppData
• Linux: Checks /usr/bin/google-chrome, /usr/bin/chromium, /snap/bin/chromium
• .doc conversion: Uses textutil on macOS, libreoffice on Linux

Limitations

• No support for footnotes, images, or links (Markdown image URLs are not fetched)
• Math equations (LaTeX) are preserved as plain text
• Nested lists deeper than one level are flattened
• Template detection works best with templates that have clear formatting differentiation between headings and body text