huashu-md-html: one skill that turns documents into markdown, then into typeset html or publisher-grade docx

The premise: markdown is the source code

The repository states its philosophy in one line: markdown is the source code, html and docx are the build products. Everything in the skill follows from that. Arbitrary inputs, including PDF, DOCX, PPTX, XLSX, EPUB, images, audio, YouTube videos and web page URLs, get converted into clean markdown first. That markdown then feeds a styled html build, or a docx build aimed at editorial workflows. Published html can be pulled back into markdown for archiving. The author describes the skill as needing no buttons, no panels and no GUI: you talk to your agent, the agent runs scripts. The README lists example requests, such as turning a PDF into markdown, dressing a markdown article with the article theme, pulling a blog URL back to markdown without navigation and sidebars, or assembling chapter markdown files into a docx a publisher can review.

Four capabilities and what runs underneath

Each capability is one command with a named underlying tool. Capability one, anything to markdown, uses microsoft/markitdown through scripts/any_to_md.py. Capability two, markdown to styled html, uses pandoc plus four custom themes through scripts/md_to_html.py. Capability three, html or a URL back to markdown, uses the html-to-markdown library plus trafilatura through scripts/html_to_md.py. Capability four, markdown to publisher-grade docx, uses python-docx with built-in typesetting presets through scripts/md_to_docx.py. The decision principles in the README are worth reading because they encode workflow judgments: the markdown from capability one feeds capability two directly, making a PDF to styled html one chain; capability three exists for archiving already-published pages back to source; and capability four is the publishing endpoint, meant for human editors, on the argument that the professional publishing world settles on docx.

The URL routing rule

A URL input can go through either capability one, markitdown, or capability three, trafilatura, and the README is direct that the output quality differs enormously by page type. Structured pages such as product details, technical docs, API documentation, certificate pages and e-commerce items should go to markitdown, because it preserves metadata, field values, links and heading hierarchy. Prose pages such as blogs, news, essays and long articles should go to trafilatura, because it strips navigation, sidebars, related recommendations and advertisements, leaving the body text. For uncertain cases the rule is to run both and compare, choosing whichever output suits the downstream use. The stated heuristic is to ask whether the content on the URL is for reading or for lookup: reading goes to trafilatura for noise removal, lookup goes to markitdown to keep the information.

Four html themes and the anti-slop checklist

The styled html output comes from four themes, each with a named design anchor. article takes cues from Tufte CSS and Pentagram-style information building, with margin notes and side distances, aimed at essays, blogs and long reads. report follows white-paper conventions with dense multi-table layouts for technical reports, research and product documents. reading is a Medium-like minimal single-column style for reposts and light reading. interactive adds folded sections, a table of contents and a sidebar for handbook chapters and long tutorials. Every theme passes what the README calls an anti AI slop checklist: no purple gradients, no cyberpunk decoration, no dark dashboard backgrounds, no emoji as formal icons, and copied colors that hold a publishing position. Each theme is self-contained CSS, so the html opens directly without external CDNs. A shared typography baseline defines the fonts, line heights, body sizes and maximum widths for Chinese and English text and code blocks.

Installing and the docx endpoint

Installation is one command through the skills CLI, and the README notes the skill is agent agnostic, working with Claude Code, Cursor, Codex, OpenClaw and Hermes.

npx skills add alchaincyf/huashu-md-html

After that you speak to the agent rather than memorizing flags. The docx capability deserves its own mention because the README explains why it exists separately from pandoc: plain pandoc docx output defaults to Calibri, has no table styles, no cover and flat chapter pages, fine for a machine to read but not something a publisher editor will accept. The md_to_docx.py script embeds publisher-grade typesetting presets and supports a book mode that adds a cover, table of contents, running heads and chapter breaks across multiple files.

python3 scripts/md_to_docx.py article.md

The same script takes several markdown files at once for the book workflow, with title, subtitle and author passed as options, which is the path for turning a set of chapters into a reviewable manuscript.

Limits to know

The skill is a set of scripts that call python3, pandoc and their underlying libraries, so a machine without those tools is not a target environment, and there is no GUI or standalone server by design. The typography baseline is Chinese-first, with PingFang SC and Source Han Serif leading the Chinese font stacks and Chinese line heights specified separately, so English-only documents get the English stacks but the design judgment clearly centers Chinese reading. The html themes are for reading surfaces, not application UI, and the ban list means anyone wanting gradient-heavy marketing pages should look elsewhere. Conversion quality for exotic inputs still depends on the underlying tools: markitdown and trafilatura define the ceiling for capability one and three, and pandoc defines the markdown parsing for capability two. The README is candid that the demos themselves were made with a separate huashu-design skill, so the promotion videos and the conversion capability are different tools.

Compared with running the tools directly

Every underlying tool here is a known open source project, so the alternative is calling markitdown, pandoc, trafilatura and python-docx yourself. For a single conversion that is often simpler. What the skill adds is the judgment layer: the URL routing table, the four themes with their typography baseline and ban list, the docx presets with cover and TOC, and the chaining principles, which is precisely the knowledge that gets rediscovered every time someone assembles these tools manually. It also packages the whole thing as agent skill instructions, so an agent can execute a request such as turning a PPTX into a reading-theme publishable page without you writing the pipeline. If you already have a battle-tested conversion pipeline in code, keep it. If your conversions are ad hoc, frequent and varied, this skill turns that variety into conversation.

Licence and packaging

The project carries an MIT licence badge, positions itself as agent agnostic through the skills.sh ecosystem, and installs through the standard skills CLI command. There are no published releases in the repository and no version number stated in the README, so tracking changes means watching the repository itself. The structure is small by intention: scripts for each capability, theme assets, examples with output previews, and demo GIFs and MP4s produced by the companion design skill. For a content operation that already runs agents, the integration cost is near zero, and the risk is correspondingly contained, since the worst case is that a theme does not suit your brand and you edit its CSS, which the README expects, given that every theme is self-contained single-file CSS with no external dependencies.

Editorial conclusion

Take huashu-md-html if your content workflow already lives inside an agent, because the four conversion capabilities chain cleanly, the URL routing rule between markitdown and trafilatura removes a real decision, and the docx output targets human editors rather than machines, which is the part pandoc alone does not do. The four html themes carry specific typography and an explicit ban list against gradient decorations and emoji icons, so the output reads like a publication instead of a dashboard. Skip it if you need a standalone converter with a GUI, since there is none here by design, or if you are on a machine without python3 and pandoc available, because the scripts call them directly. For batch publishing pipelines, the md as source code philosophy is the reason to prefer this over piecing the tools together yourself.

Frequently asked questions

Official sources

1. alchaincyf/huashu-md-html on GitHub
2. Issues
3. License: MIT
4. README