huashu-md-html Publishing Pipeline
A markdown-centered publishing pipeline: turn anything into clean md, and md into publication-grade html, docx, PDF and EPUB, with a built-in anti-AI-slop aesthetic bar.
No red-line risks at documentation level: no credential theft or covert exfiltration; OPENAI_API_KEY is optional and disclosed (image description); the update check explicitly defers updating to the user, a good confirmation design. But the actual scripts are absent from the evidence, so least privilege, data flow and rollback cannot be statically verified; the git ls-remote network check is silent by design. Deducted: unverifiable permissions/isolation/rollback due to missing script bodies.
SKILL.md has a thorough error-handling table (dependency-missing prompts, empty-output warnings, macOS pip/python3 pitfall, EPUB pitfalls); paths are self-consistent and dependencies documented. But none of the six entry scripts or references appear in the evidence; no tests, no CI, no reproduction records — static ceiling is 10. Deducted: key paths not statically reproducible; failure-feedback quality is self-described only.
Decision tree, dual URL routing (read vs. lookup heuristic), explicit boundaries against sibling skills, and trigger phrasing tables are all very clear; native Chinese support. Deducted: some features (YouTube captions, some URL fetching) rely on resources possibly unreachable from mainland China, dismissed with only a check-network/VPN note; environment-fit evidence limited.
Well-layered docs (decision tree → capability details → references routing → error table), complete MIT license, clear dependency/install notes. But inconsistency exists: SKILL.md claims six capabilities while README claims four (capabilities 5/6 absent from README structure tree); no CHANGELOG/versioning scheme; maintenance responsibility rests only on a personal README intro. Deducted: version governance and cross-document consistency gaps.
Claims a one-command pipeline (PDF→md→polished html/docx/epub) with a real 158-page publisher-review docx case; the marginal-value argument over raw pandoc is well made. But all outputs are self-reported; static review cannot confirm outputs are directly usable, and the example output files are not in the evidence. Deducted: no verifiable representative outputs.
Signs of first-hand material (detailed error table, pitfall notes, named real-world case) but none independently checkable; no test suite, no CI, no third-party execution evidence; example outputs and references not present in the evidence. Deducted: single evidence type, entirely author self-report.
- The six entry scripts (any_to_md.py etc.) and references/examples are absent from this evidence; review the scripts' network requests and file writes before installing.
- Capability count is inconsistent between SKILL.md (six) and README (four); actual capabilities depend on scripts present in the repo.
- URL fetching and YouTube caption features may be unreachable from mainland-China networks; docs only suggest VPN with no fallback.
- Capability 1's --llm-describe requires OPENAI_API_KEY and sends image content to a third-party API; avoid for sensitive images.
- Heavy dependencies (markitdown[all], pandoc, playwright+chromium, etc.) mean a sizable first install.
- No test/CI evidence; known quality gaps per docs (complex tables, scanned PDFs).
What does this skill do, and when should you use it?
huashu-md-html is an Agent Skill that treats markdown as the source code of the writing loop and wires every direction of conversion into one pipeline. Six capabilities, each a single Python command: any file (PDF/DOCX/PPTX/XLSX/images/audio/URL) to md, md to html, html/URL back to md, md to publisher-grade docx, md to multi-size PDF, and md to EPUB3. The html path ships four self-contained themes (article/report/reading/interactive) governed by an anti-AI-slop checklist inherited from huashu-design. It wraps external tools such as pandoc, markitdown, html-to-markdown and trafilatura, with startup dependency self-checks and explicit install hints.
Runs six Python scripts under scripts/: any_to_md.py wraps markitdown to convert 20+ formats — PDF, DOCX, PPTX, XLSX, images, audio, YouTube URLs and plain web pages — into md (URLs can carry YAML frontmatter); md_to_html.py wraps pandoc plus four custom CSS themes to produce html, with an optional token-spending designer mode where the AI reads the content and proposes three visual directions; html_to_md.py wraps html-to-markdown and trafilatura for local html or blog-URL body extraction and archiving; md_to_docx.py uses python-docx to emit publisher-grade docx with multi-file merge, book mode (cover, TOC, header/footer) and large-32mo or A4 page sizes; md_to_pdf.py goes md→html→Playwright/Chromium to produce PDFs in A4/A5/book/Letter/Legal; md_to_epub.py uses pandoc + ebooklib to produce EPUB3 with automatic image embedding, H1-based chapter splitting and reader-compatible CSS.
- A writer or blogger converting a PDF whitepaper or YouTube video into md, then rendering a publish-ready polished web page in one step
- A book author producing a publisher-reviewable docx from chapter md files (the source documents a real 158-page review copy: 9 chapters + postscript + appendix, 57 images)
- An indie developer archiving published blog posts or scraping product/docs pages back into project md sources
- A content creator turning an article into an A4 share PDF, a physical-book-size preview, or an EPUB readable in Apple Books/Kindle
- Anyone facing an uncertain URL who wants to compare markitdown output (preserves structured fields) against trafilatura output (clean body text) before choosing
What are this skill's strengths and limitations?
- Each of six capabilities is one command; capability 1 output feeds directly into 2/5/6 for one-shot chains (PDF→md→polished html, or re-typeset a PDF)
- Four self-contained single-CSS html themes with no external CDN, each passing an anti-AI-slop checklist (no purple gradients, no emoji icons, no #0D1117 dark backgrounds)
- docx capability embeds publisher-grade presets (chapter number marks, emoji-colored quote blocks, headers/footers, book/A4 sizes), validated by a real 158-page review manuscript
- Explicit URL routing strategy: structured pages via markitdown to keep metadata, prose pages via trafilatura to strip noise, run both when unsure
- Scripts self-check dependencies at startup and print exact install commands instead of failing silently
- Heavy dependency chain: pandoc via brew, several pip packages, plus Chromium download for PDF
- Documented limits: scanned PDFs get no OCR, complex tables lose semantics, PPTX keeps only text+notes, and markitdown output is designed for LLM consumption needing re-typesetting for humans
- README describes four capabilities while SKILL.md describes six (PDF and EPUB added), so docs are out of sync
- No test suite or evidence of Windows/Linux validation; EPUB CSS deliberately avoids variables/grid for Kindle compatibility, constraining visual expression
- WeRead (微信读书) publishing and project-level book pipelines (versioning, R2 upload) are explicitly out of scope — use huashu-book-pdf instead
How do you install this skill?
Run npx skills add alchaincyf/huashu-md-html in a terminal (per the source it is agent-agnostic — Claude Code, Cursor, Codex and others can install it). Then install dependencies: python3 -m pip install 'markitdown[all]' html-to-markdown trafilatura python-docx Pillow, brew install pandoc; for PDF also python3 -m pip install playwright && python3 -m playwright install chromium, and for EPUB python3 -m pip install ebooklib. On macOS use python3 -m pip rather than bare pip.
How do you use this skill?
After installing, trigger it in an Agent Skills-compatible agent with plain language, e.g. "convert this PDF to md", "turn this md into polished html with the article theme", "archive this blog URL back to md", "make these chapter md files into a publisher-reviewable docx". You can also run scripts directly, e.g. python3 scripts/md_to_html.py article.md --theme report -o out.html or python3 scripts/md_to_docx.py ch*.md --book --title ... --author ... -o book.docx. SKILL.md insists on clarifying capability, source/destination, template and image handling up front rather than guessing mid-task.
How does this skill compare with similar options?
The source explicitly contrasts itself with pandoc's stock md→docx/md→epub output (default Calibri, unstyled tables, no one-command multi-file book assembly with embedded images), and draws a boundary with the sibling skill huashu-book-pdf (which handles WeRead publishing and the full book pipeline); its aesthetic bar is inherited from huashu-design.