Docs
[!CAUTION] Do not write your own renderer. Do not use fpdf, reportlab, or puppeteer code directly. Do not use
python -cornode -e. Ifconvert.pyfails, report the error. Do not improvise.
This skill provides unified document conversion between Markdown and presentation/document formats (PDF, DOCX, PPTX) as well as extracting existing documents back into structured Markdown.
Permissive Library Licenses
All tools and runtime dependencies used by this skill are permissively licensed:
- ReportLab (PDF generation): BSD-3-Clause
- python-docx (DOCX generation): MIT
- python-pptx (PPTX generation): MIT
- MarkItDown (document to Markdown extraction): MIT
- matplotlib (charts saved as PNG): Matplotlib License (BSD-style)
- Noto Sans KR (bundled Korean font): SIL OFL 1.1
Routing by Direction
Select the conversion guide matching the desired direction:
All three output formats share the same templates, so one --template value
means the same document identity everywhere: report, proposal, minutes.
| Direction | Guide Reference | Outputs |
|---|---|---|
| Markdown -> PDF | references/md-to-pdf.md | .pdf |
| Markdown -> DOCX | references/md-to-docx.md | .docx |
| Markdown -> PPTX | references/md-to-pptx.md | .pptx |
| Document -> Markdown | references/to-md.md | Text extraction via MarkItDown |
Fixed Command Form
Before first conversion or when troubleshooting dependencies, run the doctor command:
powershell -NoProfile -ExecutionPolicy Bypass -File "<skill-base-dir>/scripts/doctor.ps1"
(On Linux/macOS: uv run --no-project --python 3.12 "<skill-base-dir>/scripts/convert.py" --doctor)
The doctor discovers a working Python environment, provisions a persistent virtualenv outside the managed skill directory (at ~/.libragent/skills/docs/venv), verifies dependencies, and prints Doctor: OK along with the VenvPython: executable path. It installs the Word, PowerPoint and Excel converters too, so --to md works on .docx, .pptx and .xlsx files after a single doctor run.
Then run document conversion using the interpreter reported under VenvPython:. Always use the fixed command form. Give file paths only. Do not use inline code. Do not use pipes. The command must run in Windows PowerShell 5.1:
& "<venv-python-from-doctor>" "<skill-base-dir>/scripts/convert.py" --in "<abs.md>" --to pdf --template report --out "<abs.pdf>"
(On Linux/macOS: "<venv-python-from-doctor>" "<skill-base-dir>/scripts/convert.py" --in "<abs.md>" --to pdf --template report --out "<abs.pdf>")
Images, Charts and Diagrams
- No raw HTML. HTML is removed from every output, with a warning. Use Markdown tables and text.
- Images: put
alone in its own paragraph. Use a local PNG or JPEG. A relative path is read from the folder of the.mdfile. The image is scaled to the page or slide width. A missing file shows its caption instead, with a warning. - Charts: write a small matplotlib script file and run it with the doctor's
VenvPython:. Save the chart as PNG next to the.mdfile and reference it with. - Mermaid stays a code block labeled "Diagram (Mermaid)". To show a diagram as a picture, draw it as a PNG and use image syntax.
- Check the image references before converting:
& "<venv-python-from-doctor>" "<skill-base-dir>/scripts/check.py" --md "<abs.md>". This reports missing or empty images.
Output Contract & Verification
The script enforces an explicit output contract on every execution:
- On success, it prints the absolute output path,
ExitCode: 0, andOK. Every format also prints its size asBytes: <n>, plus one count for the format:Pages:for pdf,Sections:for docx,Slides:for pptx. - Only the PDF count is a page count. Word and PowerPoint lay out pages when the file is opened, so they cannot be counted here.
Sections:is always1because the writer creates one Word section: read it as a signature that the DOCX was written, not as a measurement. Use--to pdfwhen you need a page count. - On failure (including syntax/argument errors, missing files, or pending sub-issue engines), it prints the error description,
ExitCode: <n>, a singleNEXT:line guiding the next action, and exits non-zero without printingOK. - No OK line, no success report: Never claim conversion succeeded unless
convert.pyprintedExitCode: 0andOK, and the output file exists with non-zero size.