z-md-to-word

Markdown to Word

Use This For

• A local .md article needs to become a Word file.
• The user says "convert to doc", "convert to Word", "md to doc", "Markdown to Word", "export Word", or similar.
• The input is usually an Obsidian or WeChat article with YAML frontmatter and remote images.

Completion Standard

Finish only after all of these are true:

• The .docx file exists under output/doc/.
• If the user asked for .doc, a legacy .doc file also exists.
• The document can be opened or rendered by LibreOffice.
• The extracted text includes representative beginning, middle, and ending content.
• Valid images are embedded; empty upload placeholders like ![]( ) or ![Uploading file...]() are skipped.
• Markdown lists are readable as lists, even when the source omitted a blank line before -.

Preferred Command

From the workspace root:

python3 .agent/skills/z-md-to-word/scripts/md_to_word.py "/absolute/path/to/article.md"

The script writes outputs to:

output/doc/<markdown-stem>.docx
output/doc/<markdown-stem>.doc

Use --no-doc only when the user explicitly wants .docx only.

Workflow

1. Confirm the Markdown file exists.
2. Run the bundled script.
3. Read the JSON summary printed by the script.
4. If rendered_docx or rendered_doc is false, fix the cause and rerun.
5. If layout quality matters, rerun with --keep-render, open the generated contact sheet, and inspect the pages.
6. Report only the final file paths and the verification result.

Details Captured By The Script

• Uses Pandoc with markdown+yaml_metadata_block+lists_without_preceding_blankline.
• Preserves frontmatter title, author, and date as Word document metadata/title block.
• Removes empty image nodes before conversion, so upload placeholders do not appear in the final document.
• Embeds valid local or remote images into the .docx.
• Converts .docx to .doc through LibreOffice when available.
• Validates the .docx ZIP structure.
• Extracts plain text for a content sanity check.
• Renders Word files to PDF when LibreOffice is available.

Fallback

If the script cannot run, use this direct conversion pattern:

pandoc "input.md" \
  --from markdown+yaml_metadata_block+lists_without_preceding_blankline \
  --to docx \
  --standalone \
  --resource-path="/path/to/input-dir:/workspace/root" \
  --lua-filter="/tmp/remove-empty-images.lua" \
  --output "output/doc/name.docx"

/tmp/remove-empty-images.lua:

function Image(img)
  if img.src == "" then return {} end
end

Then render and inspect:

soffice -env:UserInstallation=file:///tmp/lo_profile_$$ \
  --headless --convert-to pdf --outdir tmp/docs/check "output/doc/name.docx"