mark-to-win

name	mark-to-win
description	Convert AI-generated Markdown into office documents: Word .docx, PDF .pdf, and Excel .xlsx. Use when the user asks to export or convert Markdown/AI output to Word, PDF, Excel, md to docx/pdf/xlsx, report export, table export, document generation, or mentions 马克吐文.

马克吐文

Use this skill when the user wants to convert Markdown generated by AI into Word, PDF, or Excel files. Triggers include Markdown to Word, Markdown to PDF, Markdown to Excel, md to docx, md to xlsx, md to pdf, report export, document export, and "马克吐文".

Purpose

马克吐文 turns Markdown into practical office documents:

• Word (.docx) for reports, proposals, resumes, meeting notes, and long-form documents.
• PDF (.pdf) for fixed-layout sharing, submission, or archiving.
• Excel (.xlsx) for Markdown tables, structured lists, comparisons, schedules, budgets, and tabular AI output. ⚠️ Unstable: complex tables may lose formatting or structure.

Workflow

1. Identify the source Markdown.

   • If the user provides Markdown inline, save it to a temporary .md file in the workspace.
   • If the user provides a file path, use that file directly.
   • If there are multiple Markdown files, ask which one unless the target is obvious.

2. Identify the target format.

   • Use .docx for Word.
   • Use .pdf for PDF.
   • Use .xlsx for Excel.
   • If the user asks for more than one format, generate each requested output.

3. Prefer high-fidelity tools when available.

   • Use scripts/mark_to_win.py with --engine auto by default.
   • If pandoc is available, auto prefers it for Word and PDF because it handles more Markdown extensions.
   • For .docx, scripts/mark_to_win.py can produce a functional document with headings, lists, code blocks, blockquotes, tables, and paragraphs.
   • For .xlsx, scripts/mark_to_win.py extracts Markdown tables into sheets and can fall back to a structured text sheet.
   • For .pdf, prefer the HTML PDF engine when Chrome/Chromium/Edge is available: Pandoc renders Markdown to styled HTML, then Chrome prints PDF. This is the closest built-in route to Markdown reader appearance.
   • Use Pandoc's direct PDF engine (xelatex, lualatex, typst, etc.) for academic/LaTeX-style PDFs when those engines are installed.
   • Use the native ReportLab fallback only when Pandoc/Chrome are unavailable or the user explicitly asks for dependency-light output.
   • For math, footnotes, citations, raw HTML, grid tables, and task lists, use Pandoc when possible. If Pandoc is unavailable, tell the user that the native fallback preserves unsupported features mostly as plain text.

4. Name outputs clearly.

   • Default output names should use the input stem plus the extension, such as report.docx, report.pdf, or report.xlsx.
   • When converting inline Markdown, choose a short descriptive filename from the user's request.

5. Verify the result.

   • Confirm that the output file exists and has nonzero size.
   • For Excel, mention how many Markdown tables were converted.
   • For PDF, mention if a fallback renderer was used because PDF fidelity varies by renderer.

Script Usage

Run the helper from this skill directory:

python scripts/mark_to_win.py input.md --to docx --output output.docx --engine auto
python scripts/mark_to_win.py input.md --to xlsx --output output.xlsx
python scripts/mark_to_win.py input.md --to pdf --output output.pdf --engine auto

Create a Markdown-reader-style PDF with Chrome and keep the intermediate HTML for inspection:

python scripts/mark_to_win.py input.md --to pdf --output output.pdf --engine html --keep-html

Inspect special Markdown features before converting:

python scripts/mark_to_win.py input.md --to pdf --output output.pdf --show-features

Require Pandoc and fail instead of falling back:

python scripts/mark_to_win.py input.md --to docx --output output.docx --engine pandoc

Force the dependency-light native converter:

python scripts/mark_to_win.py input.md --to pdf --output output.pdf --engine native

For PDF output with a specific Chinese font:

python scripts/mark_to_win.py input.md --to pdf --output output.pdf --pdf-font C:\Windows\Fonts\msyh.ttc --pdf-bold-font C:\Windows\Fonts\msyhbd.ttc

Generate multiple formats:

python scripts/mark_to_win.py input.md --to docx,pdf,xlsx --output-dir exports

Compatibility Matrix

Markdown feature	Native Word/PDF	Pandoc Word/PDF	Excel behavior
Headings, paragraphs, lists, blockquotes	Supported	Supported	Stored as structured text only when no tables exist
Fenced code blocks	Supported as preformatted text	Supported with better styling	Stored as structured text only when no tables exist
Pipe tables	Supported	Supported	Converted to worksheets
Chinese/Japanese/Korean text in PDF	Supported by CJK font discovery	Supported when PDF engine has a CJK font	Preserved as cell text
TeX math, such as $x^2$ or $$...$$	Preserved as plain formula source	Best path; DOCX can become Office math, PDF depends on LaTeX engine	Preserved as text
Footnotes	Preserved as markers/text	Supported	Preserved as text
Task lists	Preserved as checkbox text	Better preservation	Preserved as text
Raw HTML	Partial/plain text	Better, depending on output format	Preserved as text
Grid tables	Not supported by native parser	Supported	Not extracted unless converted to pipe tables first
Mermaid, PlantUML, Graphviz	Preserved as code source	Requires pre-rendering or a Pandoc filter	Preserved as text
Citations/bibliography	Preserved as citation keys	Requires Pandoc bibliography inputs	Preserved as text
Images	Native keeps alt text	Can embed local images when paths are valid	Not embedded

Engine Selection

• Use --engine auto for most user requests.
• For PDF that should look like a Markdown preview, use --engine html. It requires Pandoc and Chrome/Chromium/Edge, but not TeX.
• Use --engine pandoc when the user explicitly needs math, footnotes, citations, raw HTML, or high-fidelity DOCX/PDF.
• Use --engine native when the environment has no Pandoc or the document is simple.
• If pandoc is missing, do not claim full support for advanced Markdown. Generate the fallback only if preserving unsupported features as plain text is acceptable.
• For PDF math, Pandoc also needs a PDF engine such as xelatex, lualatex, typst, tectonic, pdflatex, wkhtmltopdf, weasyprint, prince, or pagedjs-cli. Prefer xelatex/lualatex for CJK-heavy academic documents, and typst when the user wants a lighter modern toolchain.
• For Mermaid/PlantUML/Graphviz, render diagrams to image files first, then reference those images from Markdown for Word/PDF export. Without a renderer, the HTML engine shows the diagram source in a styled code block.

Markdown Reader PDF Notes

• The HTML PDF engine runs pandoc --to html5 --mathml, injects GitHub-like reader CSS, then prints with Chrome headless.
• It supports rendered math through browser MathML, footnotes, HTML tags supported by Chrome, task-list checkboxes, code blocks, tables, and CJK text.
• It does not render Mermaid by itself unless a Mermaid renderer is added separately.
• If Chrome is installed outside PATH, pass --browser "C:\Program Files\Google\Chrome\Application\chrome.exe" or set MARK_TO_WIN_BROWSER.

Formatting Guidance

• Preserve the document hierarchy from Markdown headings.
• Treat fenced code blocks as preformatted text.
• Convert Markdown tables into real Word tables or Excel worksheets.
• For PDF, do not rely on ReportLab's default Helvetica font for Chinese text. Use the helper's automatic CJK font discovery or pass --pdf-font.
• Keep Excel sheets focused on tabular data; do not flatten a narrative document into hundreds of awkward rows unless the user explicitly asks for that.
• For Word/PDF, preserve narrative flow and tables.
• If the Markdown contains image links, keep the link text when image embedding is unavailable.

Dependencies

The helper script uses optional Python packages when installed:

• python-docx for Word output.
• openpyxl for Excel output.
• reportlab for PDF fallback output.

If an optional dependency is missing, explain which package is needed for that target format and use another available route if possible.