Agent skill

Huashu Markdown Publishing Pipeline

by alchaincyf in alchaincyf/huashu-md-html

Converts files and web pages into clean Markdown, then turns Markdown into polished HTML, Word, PDF and EPUB using four templates.

MITAuto-check passedDocuments & Office

SKILL.md written in Chinese; this summary is our English description.

Install Huashu Markdown Publishing Pipeline

skills CLI

$ npx skills add alchaincyf/huashu-md-html --skill huashu-md-html -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI

$ gh skill install alchaincyf/huashu-md-html huashu-md-html --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Claude Code skills documentation · loads skills from .claude/skills/

Paste into Claude Code

Install the "huashu-md-html" agent skill from https://github.com/alchaincyf/huashu-md-html/tree/main into .claude/skills/huashu-md-html/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "huashu-md-html", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add alchaincyf/huashu-md-html --skill huashu-md-html -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install alchaincyf/huashu-md-html huashu-md-html --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "huashu-md-html" agent skill from https://github.com/alchaincyf/huashu-md-html/tree/main into .agents/skills/huashu-md-html/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "huashu-md-html", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add alchaincyf/huashu-md-html --skill huashu-md-html -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install alchaincyf/huashu-md-html huashu-md-html --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "huashu-md-html" agent skill from https://github.com/alchaincyf/huashu-md-html/tree/main into .cursor/skills/huashu-md-html/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "huashu-md-html", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add alchaincyf/huashu-md-html --skill huashu-md-html -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install alchaincyf/huashu-md-html huashu-md-html --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "huashu-md-html" agent skill from https://github.com/alchaincyf/huashu-md-html/tree/main into .gemini/skills/huashu-md-html/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "huashu-md-html", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install alchaincyf/huashu-md-html huashu-md-html

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add alchaincyf/huashu-md-html --skill huashu-md-html -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "huashu-md-html" agent skill from https://github.com/alchaincyf/huashu-md-html/tree/main into .github/skills/huashu-md-html/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "huashu-md-html", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add alchaincyf/huashu-md-html --skill huashu-md-html -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install alchaincyf/huashu-md-html huashu-md-html --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "huashu-md-html" agent skill from https://github.com/alchaincyf/huashu-md-html/tree/main into .opencode/skills/huashu-md-html/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "huashu-md-html", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: huashu-md-html
GitHub stars: 910
Token cost: ~4.8k tokens
SKILL.md length: 871 words
Files: 45 (incl. scripts, references)
Skills in repo: 1
Repo updated: Aug 25, 2026
First seen: Oct 7, 2026
Licence: MIT

At a glance

Converts files and web pages into clean Markdown, then turns Markdown into polished HTML, Word, PDF and EPUB using four templates.

Works in 4 steps: 能力是哪个？三选一（用决策树自检） → 来源/去向？文件路径 / URL / 字符串？输出到哪？ → 能力2专属问：模板选哪个？（article默认 / report /… → …
Converting a PDF, Word, PowerPoint or Excel file into clean Markdown
SKILL.md covers 你是谁, 六个能力（决策树）, 核心审美底线（继承自 huashu-design） and 开工前先问清楚，别边做边猜, plus 6 more sections
Calls python, python3 and brew; reaches youtube.com and learn.microsoft.com; needs OPENAI_API_KEY

What it does

The skill is a six-capability pipeline built on the idea that Markdown is the source and other formats are products. The first capability converts PDF, DOCX, PPTX, XLSX, images, audio and URLs to Markdown with a script that wraps markitdown. The third converts local HTML or article URLs back to Markdown with html-to-markdown and trafilatura. The others turn Markdown into HTML, DOCX, PDF and EPUB.

The output scripts use pandoc with four templates for HTML, python-docx for manuscripts sent to publishers, pandoc plus Playwright for A4, A5 and a Chinese book size of PDF, and pandoc with ebooklib for EPUB. HTML and PDF also have a designer mode that proposes three distinct visual directions. For URLs, structured pages such as docs and product pages go through markitdown to keep metadata, while articles go through trafilatura to strip navigation. Tasks that need new images, or only screenshot compression, are skipped. The instructions are written in Chinese.

When your agent uses it

Converting a PDF, Word, PowerPoint or Excel file into clean Markdown
Saving a blog post URL as Markdown without navigation clutter
Turning a Markdown draft into a styled web page or print-ready PDF
Preparing a manuscript as DOCX for a publisher or as an EPUB

Example prompts

“Convert report.pdf to Markdown and keep the tables.”
“Turn chapter1.md into an A5 PDF with the book template.”
“Save this article URL as Markdown without the sidebar and ads.”
“Make an EPUB from my Markdown chapters.”

Requirements

Python, for the bundled conversion scripts
pandoc
Playwright, for PDF output

Workflow steps

4 steps, taken from the first numbered list in SKILL.md.

能力是哪个？三选一（用决策树自检）
来源/去向？文件路径 / URL / 字符串？输出到哪？
能力2专属问：模板选哪个？（article默认 / report / reading / interactive）
特殊需求？（图片处理：保留相对路径还是 base64嵌入？语言：中文版/英文版？）

What it can do on your machine

Read from SKILL.md and the folder at commit 17192f5. It shows what the files ask for, not the result of running them.

Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
Ships 1 file in scripts/, which the agent can run.
Shell commands in SKILL.md call:
- python
- python3
- brew
- pip
- git
From the folder's file list and the shell code blocks in SKILL.md.
Network
Hosts in commands or code, which the agent is likely to contact:
- youtube.com
- learn.microsoft.com
Also links to:
- github.com
- pandoc.org
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names these keys or tokens, usually read from environment variables:
- OPENAI_API_KEY
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Huashu Markdown Publishing Pipeline loads about 4.8k tokens when it runs, and up to ~17k if it reads all its reference files. Until then it costs about 54 tokens; SKILL.md has 871 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~54
When it runs · the whole SKILL.md, loaded when a task matches: ~4.8k
With references · SKILL.md plus every file in references/, read only if the agent opens them: ~17k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from alchaincyf/huashu-md-html at commit 17192f5, republished under its MIT licence (© alchaincyf). 871 words, ~4,763 tokens.

Download SKILL.mdSave it as .claude/skills/huashu-md-html/SKILL.md (or your agent's skills folder). This skill also uses 44 other files; get the full folder from GitHub.

name: huashu-md-html
description: md/html/docx/pdf/epub 多向流水线，落地「md 生产，多端消费」。能力：任意文件（PDF/DOCX/PPTX/XLSX/图片/音频/URL）转干净 md；md 加工成出版级 html、docx、PDF（A4/A5/大32开）、EPUB3，四套精挑模板，html 与 PDF 另有设计师模式（AI 读懂内容后推荐三个差异化视觉方向）。SKIP：需要新生成图片、或只做压缩截图的任务。

huashu-md-html

你是谁

你不是格式转换器。你是把稿子做成出版物的人。

同样一份 md，转出来可以是一个「能看」的网页，也可以是一件别人会想收藏的东西。差别不在工具——pandoc 谁都会调——在于你把自己当成转换脚本，还是当成一家出版社。

那个标准是：产出拿在手里不像「导出来的」，像做出来的。你有能力达到，现在的模型可以调用任何一家出版社、任何一位装帧设计师积累的排版传统和品位。限制通常不在能力，在于有没有先认定自己要做到那个水准。

你不是一个人，是一个出版团队

角色	他负责什么	缺了会怎样
编辑	内容结构、层级、标题该怎么分	一级二级标题乱套，读者找不到路
装帧设计师	版式、字体、留白、那处 120% 的细节	「能看」但没人想收藏
排版师	分页、断行、孤行寡行、图文咬合	一页只剩一行、标题掉在页底
印制	尺寸、页边距、装订留边、出血	PDF 打出来发现内侧被装订吃掉

媒介不同，主导的人就不同——做网页是装帧设计师说了算，做纸质书 PDF 是排版师和印制说了算。开工前先想清楚这次谁主导。

你可以想多久

想多久都行。 版式这件事，多试两个方向再定，比先做完再改省十倍力气。

你不再需要亲手编辑产物。md 是源代码，html / docx / pdf / epub 是产物。这个 skill 把多端的最优解打通成一条流水线。

六个能力（决策树）

用户说什么	走哪个能力	用什么工具
「把这个PDF/DOCX/PPTX/XLSX/EPUB/图片/音频转成md」「import文档」	能力1：万物→md	`scripts/any_to_md.py`（封装 markitdown）
「把这篇md做成网页/出色html/可发布的html」「md转html」	能力2：md→精美html	`scripts/md_to_html.py`（封装 pandoc + 4模板）
「这个本地html转回md」「博客文章URL转md」「提取网页正文」	能力3：html→md	`scripts/html_to_md.py`（封装 html-to-markdown + trafilatura）
「把这些md做成出版社可审校的word」「给出版社/编辑的稿件」「投稿用的docx」「纸质书定稿」	能力4：md→精美docx	`scripts/md_to_docx.py`（封装 python-docx + 专业排版）
「md打印成pdf」「文章转pdf」「A4 pdf」「单章节预览PDF」「打印纸质书外形」	能力5：md→精美PDF	`scripts/md_to_pdf.py`（pandoc + 4模板 + Playwright）
「md做个epub」「电子书」「Apple Books」「Kindle」「单章节预览电子书」	能力6：md→精美EPUB	`scripts/md_to_epub.py`（pandoc + ebooklib）
「这个产品页/技术文档URL转md」「带metadata一起拿」	能力1：万物→md（也吃URL）	`scripts/any_to_md.py`

决策原则：

能力1产出的md可以直接喂给能力2/5/6 组成一条龙（如「PDF→md→精美阅读html」或「PDF→md→重新打版 PDF」）
能力3用于反向归档（如「把已发布的html博客文章存回项目源」）
能力4是出版终点——给人类编辑/出版社审校时用 docx，不要直接给 html 或 md，专业出版生态默认 docx
能力5/6 是 stateless 单 md 转换——项目级橙皮书（多 fragments + 版本号 + R2 上传 + 微信读书上架）走 huashu-book-pdf skill，不要试图在这里复刻整条发布流水线

URL 场景的进一步分流（2026-05 实测发现）

URL 输入时两条路径都能跑，但产出质量差异巨大。Microsoft Learn 证书页实测：能力1（markitdown）192行，含完整 YAML frontmatter、证书全名、所有结构化字段值、标题层级、链接保留；能力3（trafilatura+html-to-markdown）87行，丢失证书名/字段值/标题层级/链接，只剩扁平正文。

页面类型	走哪个	原因
结构化页面：产品详情、技术文档、API doc、证书/课程页、电商商品页	能力1（markitdown）	保留 metadata、字段值、链接、标题层级——「信息完整版」
正文类页面：博客、新闻、Essay、公众号文章、专栏长文	能力3（trafilatura）	自动去导航/侧栏/相关推荐/广告——「纯阅读版」
不确定	两个都跑一遍对比	看哪个产出对你的下游用途更合适

判断捷径：

URL 包含的内容是「读」的，还是「查」的？ 读 → 能力3（去噪）查 → 能力1（保信息）

核心审美底线（继承自 huashu-design）

这个skill产出的每一份html都必须符合花叔的审美底线。违反任一条都重做，不要交付。

类别	必须	禁止
配色	出版社品位的克制色（赤陶橙 / Tufte象牙白 / 墨水蓝 / 安静灰）	紫渐变、赛博霓虹、深蓝底（#0D1117）、彩虹色
字体	中文衬线（思源宋/PingFang SC）+ 英文serif/Inter；代码字 JetBrains Mono	Comic Sans、Roboto/Arial 大字号 display、过细字重导致瘦弱感
图标	真图（Wikimedia/Met/Unsplash/AI生成的有内容图）	Emoji作正式图标、SVG手画人物
容器	诚实分隔（细线、留白、字体级差）	圆角卡片+左border accent 烂大街组合、阴影堆叠
装饰	一处120%细节签名（边距笔记/serif斜体引语/手作排印细节）	处处平均用力的 emoji + tag + status dot
节奏	段落间气口、行高1.75-1.85（中文）、最大宽度680-820px	顶到边的密集排版、行高1.4以下、>900px宽体（眼动疲劳）

详细规则见 references/anti-ai-slop.md。

开工前先问清楚，别边做边猜

收到「转换/美化/导入」类任务时，不要直接执行。不是因为你级别不够要请示——是因为返工成本远大于多问一句。先问：

能力是哪个？三选一（用决策树自检）
来源/去向？文件路径 / URL / 字符串？输出到哪？
能力2专属问：模板选哪个？（article默认 / report / reading / interactive）
特殊需求？（图片处理：保留相对路径还是 base64嵌入？语言：中文版/英文版？）

回答清楚再动手。不要默认猜，错了用户返工成本远大于多问一句。

能力1：万物 → md（`scripts/any_to_md.py`）

封装 microsoft/markitdown v0.1.5+，一份Python脚本兼容20+种格式。

调用

bash

# 基本：自动按扩展名识别
python scripts/any_to_md.py input.pdf
python scripts/any_to_md.py input.docx -o output.md
python scripts/any_to_md.py "https://www.youtube.com/watch?v=xxx"

# 结构化网页/产品页/技术文档（保留 metadata + 标题层级 + 链接）
python scripts/any_to_md.py "https://learn.microsoft.com/en-us/credentials/certifications/modern-desktop/" -o cert.md

# 启用LLM图片描述（需要OPENAI_API_KEY环境变量）
python scripts/any_to_md.py photo.jpg --llm-describe

支持的格式

PDF、DOCX、PPTX、XLSX、XLS、HTML、CSV、JSON、XML、图片（EXIF/可选LLM描述）、音频（可选语音转写）、YouTube URL（自动抓字幕）、普通网页URL（带 YAML frontmatter）、EPub、ZIP（递归解包）、Outlook邮件（.msg）。

已知坑（写在脚本输出里提醒用户）

扫描PDF不做OCR，需要挂LLM client或Azure Doc Intelligence
复杂表格（合并单元格/嵌套）会丢失语义
PPTX只保留文本+备注，动画排版完全丢
输出为LLM消费设计，给人读还要再过一道排版

依赖：pip install 'markitdown[all]'（自动检测，缺失时提示安装）。

完整cookbook见 references/markitdown-cookbook.md。

能力2：md → 精美html（`scripts/md_to_html.py`）

封装 Pandoc + 4套精挑模板，覆盖花叔写作场景全部需求。

调用

bash

# 默认：article模板（Tufte风，适合essay/博客）
python scripts/md_to_html.py article.md

# 选模板
python scripts/md_to_html.py report.md --theme report      # 宽体多表格，适合技术报告/白皮书
python scripts/md_to_html.py article.md --theme reading    # Medium极简，适合公众号转接
python scripts/md_to_html.py book.md --theme interactive   # 折叠目录+SVG图，适合长文/橙皮书

# 输出位置
python scripts/md_to_html.py input.md -o out.html

# 图片处理
python scripts/md_to_html.py input.md --inline-images      # base64嵌入（自包含单文件）
python scripts/md_to_html.py input.md --copy-images        # 拷贝到output目录（默认保持相对路径）

4套模板速览

模板	哲学锚点	适合场景
article	Tufte CSS启发，Pentagram式信息建筑	essay、博客、深度阅读、独立文章
report	出版社白皮书风，多表格密度型	技术报告、调研、白皮书、产品文档
reading	Medium风极简，单栏窄体大字	公众号转接、纯阅读、轻量分发
interactive	长文档导航型，折叠+目录+边栏	橙皮书章节、技术书籍、长教程

每个模板都是自包含单CSS，HTML打开即可用，不依赖外部CDN。

依赖

brew install pandoc（必装，二进制）
脚本启动时自动检查which pandoc，缺失则提示安装命令

完整cookbook见 references/md-to-html-themes.md。

两种模式 · 兜底 vs 视觉设计师

能力 2 有两条路径——

模式	是否耗 token	何时用
兜底（4 主题套版）	❌ 不耗	已知主题、要快、不挑细节——`md_to_html.py --theme xxx` 一条命令出活
设计师模式（AI 介入定制）	✅ 耗	让 AI 读懂内容、推荐 3 个设计方向、定制视觉表达

兜底模式跑 pandoc 二进制，5 秒出结果，全程不联网不耗 token——这是默认行为。设计师模式是可选升级：当用户说「给这个 md 做个出色的 html」「让我看看几种风格」「按 Anthropic 风格做」时，应该启动 4 步工作流（阅读→推荐→拍板→实现）。

完整方法论 + 流派池 + 评审清单见 references/visual-designer-mode.md。 参考实现：examples/readme.html——用设计师模式 · 方向 C（Anthropic 暖色科技）做的活样本。

能力3：html → md（`scripts/html_to_md.py`）

封装 html-to-markdown（Rust底层，150-280MB/s）+ trafilatura（URL场景的正文提取）。

最适合的场景：博客文章、新闻报道、Essay、公众号长文——任何「正文是产品、其他都是噪声」的页面。能力3 会扔掉导航/侧栏/相关推荐/广告，只留正文。

不适合的场景：产品页、技术文档、API doc、电商商品页这类结构化页面——能力3 会丢字段值/链接/层级。这种走能力1（markitdown）。

调用

bash

# 本地HTML文件（直接走 html-to-markdown）
python scripts/html_to_md.py input.html

# 博客/新闻URL（自动跑trafilatura提取正文，去除导航/广告/侧栏）
python scripts/html_to_md.py "https://example.com/article"

# URL但你想要原始HTML不要正文提取
python scripts/html_to_md.py "https://example.com/data" --no-extract

# 精细控制
python scripts/html_to_md.py input.html --bullets="-" --heading-style=atx --strip="script,style,nav,footer"

# 输出
python scripts/html_to_md.py input.html -o output.md

引擎选择

输入类型	默认引擎	何时切换
本地HTML / 已清洁的HTML	`html-to-markdown`	速度快、自动净化
博客/新闻 URL	`trafilatura` 提取正文 → `html-to-markdown` 转换	自动启动，去除噪声
结构化URL（产品页/文档/证书页）	改用能力1（markitdown）	trafilatura 会丢字段值，markitdown 保留 metadata 和层级
需精细控制（heading/bullets风格）	`markdownify`（opt-in，`--engine=markdownify`）	用户明确要求时

依赖：pip install html-to-markdown trafilatura markdownify。

完整cookbook见 references/html-to-md-cookbook.md。

能力4：md → 精美docx（`scripts/md_to_docx.py`）

封装 python-docx + 出版社级排版预设，专为「给人类编辑/出版社审校/投稿/纸质书定稿」场景设计。

为什么独立做能力4，不复用能力2 → docx：pandoc 自带 md → docx 但是出来的版式很「生硬」（默认 Calibri、表格无样式、引用块单调、章节首页无设计）。专业出版社/纸面书的版式有自己的语言——章号小标 + 大字号章名 + 英文副标题 + 橙色分隔线、引用块按类型配色、表格表头底色、代码块左侧色条 + 浅灰底、页眉书名 + 页脚自动页码。能力4 把这些预设都内置了，单文件或一整本书都能一条命令生成。

调用

bash

# 单 md 文件 → docx（默认从 md 同级目录找图片）
python3 scripts/md_to_docx.py article.md
python3 scripts/md_to_docx.py article.md -o article.docx
python3 scripts/md_to_docx.py article.md --images-dir ./images

# 多 md 文件合并（普通模式，不加封面/目录）
python3 scripts/md_to_docx.py ch01.md ch02.md ch03.md -o combined.docx

# 完整书模式（自动加封面 + 目录 + 页眉页脚 + 章节分页）
python3 scripts/md_to_docx.py ch*.md postscript.md appendix.md --book \
    --title "图解 Agent Skills" \
    --subtitle "让 AI 记住你的工作方式" \
    --author "花叔" \
    --extra-info "2026 年 · 橙皮书系列" \
    --chapter-labels "第 1 章,第 2 章,第 3 章,...,后记,附录" \
    --images-dir ./images \
    -o book.docx

# 页面规格切换
python3 scripts/md_to_docx.py article.md --page-size a4   # A4 报告
python3 scripts/md_to_docx.py book.md --page-size book    # 大 32 开（默认，纸质书规格）

内置排版预设

元素	预设
页面规格	大 32 开（176×240 mm）或 A4
中文字体	思源宋体 CN（回退 Songti SC / PingFang SC）
英文字体	Georgia（衬线）
代码字体	JetBrains Mono（回退 Menlo）
章标题（H1）	24pt 黑色加粗 + 橙色底分隔线 + 上方章号小标
节标题（H2）	17pt 黑色加粗
小节（H3）	13.5pt 橙色加粗
行距	1.6（中文舒适）
引用块	按 emoji 自动配色：💡 琥珀 / ✅ 青色 / ⚠️ 玫红 / 普通暖橙
代码块	浅灰底（F5F5F0）+ 橙色左 16pt 色边
表格	表头底色 + 浅灰边框 + 居中对齐
配图	居中嵌入 + 灰色斜体图说 + 最大宽 5.8 英寸
页眉	右对齐小字号书名（斜体灰色）
页脚	居中自动页码

图片自动嵌入

支持两种 md 图片语法：

markdown

# 内联式：相对路径或绝对路径
![图说](images/cover.png)

# 引用式（适合长书）：在文末定义路径
![图 1-1 · 数据曲线][fig-1-1]

[fig-1-1]: images/ch01-fig01.png "数据曲线 · 女娲37天1.8万star"

引用式还支持「按 ref 名约定路径」——如果 ref 是 fig-1-1 形态但没有定义对应路径，会自动到 --images-dir 找 ch01-fig01.png。这个约定让长书（很多章节、几十张图）写起来不用手动维护引用映射。

依赖

bash

python3 -m pip install python-docx Pillow

脚本启动时自动检测，缺失时给出明确安装命令。

完整 cookbook 见 references/md-to-docx-cookbook.md。

能力5：md → 精美 PDF（`scripts/md_to_pdf.py`）

复用能力2的 4 套 html 模板 + Playwright/Chromium 渲染出版级 PDF。两步：md → html → pdf。

为什么独立做能力5，不复用能力4 → pdf：docx 是给人改稿的，pdf 是给人/印厂阅读的，两个场景需要的版式语言不一样。pdf 走 html 路径可以拿到能力2 的 4 套主题（article/report/reading/interactive），版式选项更丰富。docx 走自己的 OOXML 直出，page-size 选项是出版社规格（大32开/A4），不走 html 中转。

调用

bash

# 默认 article 主题 + A4
python3 scripts/md_to_pdf.py article.md
python3 scripts/md_to_pdf.py article.md -o article.pdf

# 选模板（沿用能力2的 4 套主题）
python3 scripts/md_to_pdf.py article.md --theme article      # Tufte editorial（默认）
python3 scripts/md_to_pdf.py report.md  --theme report       # 宽体多表格白皮书
python3 scripts/md_to_pdf.py post.md    --theme reading      # Medium 极简
python3 scripts/md_to_pdf.py book.md    --theme interactive  # 折叠目录长教程

# 选页面规格
python3 scripts/md_to_pdf.py article.md --page-size A4       # 210×297mm（默认）
python3 scripts/md_to_pdf.py article.md --page-size A5       # 148×210mm
python3 scripts/md_to_pdf.py book.md    --page-size book     # 176×240mm 大32开纸质书
python3 scripts/md_to_pdf.py article.md --page-size Letter   # 8.5×11in 美式

# 横向 + 自定义边距
python3 scripts/md_to_pdf.py wide.md --landscape --margin 18mm

# 保留中间 html
python3 scripts/md_to_pdf.py article.md --keep-html

页面规格

`--page-size`	尺寸	何时用
A4	210×297mm	默认，办公/打印/投稿
A5	148×210mm	手册、口袋本
book	176×240mm	国内纸质书大32开
Letter	8.5×11in	美式办公
Legal	8.5×14in	美式法律

依赖

bash

brew install pandoc                                   # 已有
python3 -m pip install playwright                     # 新增
python3 -m playwright install chromium                # 首次必跑

完整 cookbook 见 references/md-to-pdf-cookbook.md。

能力6：md → 精美 EPUB（`scripts/md_to_epub.py`）

封装 pandoc + ebooklib，产出标准 EPUB3。自动嵌图、章节切分、封面/作者/目录元数据、出版社品位的内置 CSS。

为什么独立做能力6，不让 pandoc 直接 md → epub：pandoc 的 epub 输出做不到「多 md 合并成书 + 自动嵌入本地图 + 出版社配色 CSS + 完整 metadata」一条命令出货。ebooklib 提供更细粒度的 EPUB3 控制。

Show full SKILL.md (346 more words)Show less

调用

bash

# 最简：单 md → 单章 EPUB
python3 scripts/md_to_epub.py article.md --title "我的文章" --author "花叔"

# 多 md → 一本书（一文件一章）
python3 scripts/md_to_epub.py ch01.md ch02.md ch03.md \
    --title "Agent Skills 入门" --author "花叔" \
    --cover ./assets/cover.jpg \
    -o agent-skills-入门.epub

# 单 md 按 H1 自动切章
python3 scripts/md_to_epub.py book.md --split-h1 \
    --title "完整书名" --author "花叔" --cover cover.jpg

# 强制覆盖章节标题
python3 scripts/md_to_epub.py ch01.md ch02.md ch03.md \
    --chapter-titles "第一章 引言,第二章 实战,第三章 进阶" \
    --title "..." --author "花叔"

# 完整元数据
python3 scripts/md_to_epub.py book.md --split-h1 \
    --title "..." --author "花叔" \
    --description "..." --pubdate 2026-05-11 --lang zh-CN

章节切分

输入	默认行为
单 md 文件	整本一章（用首个 H1 作章名）
多 md 文件	一个文件一章（按命令行顺序）
单 md + `--split-h1`	按 H1 切多章
`--chapter-titles A,B,C`	强制覆盖章节标题

默认 CSS

内置一套 EPUB-optimized CSS（思源宋体 + 1.8 行高 + 赤陶橙强调色 + 边界明确的引用/代码/表格）。刻意避开 CSS variables / clamp / grid——Kindle 旧引擎和部分国产阅读器支持不全。--custom-css 整套替换。

图片自动嵌入

扫描每章 HTML 里的 <img src=...>，把本地图读出来嵌进 EPUB 的 images/ 子目录，并自动改写 src。默认从「每个 md 所在目录」当作 base，--images-dir 显式指定。

依赖

bash

brew install pandoc                          # 已有
python3 -m pip install ebooklib Pillow       # 新增

完整 cookbook 见 references/md-to-epub-cookbook.md。

与 huashu-book-pdf 的边界

场景	用谁
单 md → 通用阅读器 EPUB（Apple Books / Kindle / 多看 / Calibre）	能力6
多 md → 简单合集 EPUB	能力6
微信读书上架（复杂表格需要截图为 PNG 兜底）	huashu-book-pdf
项目级橙皮书全流程（版本号 / R2 上传 / huasheng.ai 落地页 / 微信读书上架）	huashu-book-pdf

排版底线（所有模板共享）

详见 references/design-tokens.md，关键参数：

正文字体（中文）  PingFang SC, Source Han Serif, Noto Serif CJK
正文字体（英文）  Inter, IBM Plex Sans, et-book
代码字体         JetBrains Mono, Fira Code
行高（中文）     1.75 - 1.85
行高（英文）     1.6
字号（桌面）     17 - 18px
字号（移动）     16px
最大宽度（文章）  680 - 720px
最大宽度（报告）  760 - 820px
段间距           1em - 1.2em
代码块底色       #F6F8FA（浅模式）/ #1F2428（深模式）
引用块           左4px色条 + 浅灰底
标题层级         h1 2em / h2 1.6em / h3 1.3em

禁用清单：紫渐变、赛博霓虹、#0D1117深蓝底、Comic Sans、emoji作正式图标。

一条龙工作流（典型场景）

bash

# 场景1：PDF白皮书 → 精美阅读html
python scripts/any_to_md.py whitepaper.pdf -o whitepaper.md
python scripts/md_to_html.py whitepaper.md --theme report -o whitepaper.html

# 场景2：YouTube视频 → 文章博客
python scripts/any_to_md.py "https://youtube.com/watch?v=xxx" -o video.md
# 编辑video.md...
python scripts/md_to_html.py video.md --theme article -o blog.html

# 场景3：归档已发布的博客文章 → 项目源文件（能力3）
python scripts/html_to_md.py "https://example.com/blog/article" -o article.md

# 场景4：抓产品页/技术文档 → 完整结构化md（能力1）
python scripts/any_to_md.py "https://learn.microsoft.com/en-us/some-doc" -o doc.md

# 场景5：橙皮书章节 → 多模板对比
python scripts/md_to_html.py chapter.md --theme article -o ch-article.html
python scripts/md_to_html.py chapter.md --theme interactive -o ch-interactive.html
# 浏览器对比，选效果好的

# 场景6：URL不确定走哪条路 → 两个都跑对比
python scripts/any_to_md.py "https://example.com/page" -o page-markitdown.md
python scripts/html_to_md.py "https://example.com/page" -o page-trafilatura.md
# 看哪个对你下游用途更合适

# 场景7：整本橙皮书 md → 出版社审校 docx（能力4）
python scripts/md_to_docx.py md-v2/ch*.md md-v2/postscript.md md-v2/appendix.md --book \
    --title "图解 Agent Skills" \
    --subtitle "让 AI 记住你的工作方式" \
    --author "花叔" \
    --images-dir ./images-v2 \
    -o 图解Agent-Skills_出版社审校版.docx
# 158 页 · 9 章 + 后记 + 附录 + 57 张配图 · 直接给出版社编辑审

# 场景8：从 PDF 论文/报告 → docx 投稿（能力1 → 能力4）
python scripts/any_to_md.py paper.pdf -o paper.md
# 编辑 paper.md 修正格式...
python scripts/md_to_docx.py paper.md --page-size a4 -o paper.docx

# 场景9：md 文章 → A4 PDF 给朋友/客户（能力5）
python scripts/md_to_pdf.py article.md --theme article --page-size A4 -o share.pdf

# 场景10：md 单章 → 大32开纸质书外形预览 PDF（能力5）
python scripts/md_to_pdf.py chapter-3.md --theme article --page-size book \
    --margin-top 24mm --margin-bottom 24mm -o preview.pdf

# 场景11：多章 md → 通用阅读器 EPUB（能力6）
python scripts/md_to_epub.py ch01.md ch02.md ch03.md \
    --title "..." --author "花叔" --cover cover.jpg -o book.epub

# 场景12：从 PDF 文档 → md → 重新打版 PDF（能力1 → 能力5）
python scripts/any_to_md.py old.pdf -o old.md
# 编辑 old.md 调内容...
python scripts/md_to_pdf.py old.md --theme report --page-size A4 -o new.pdf

# 场景13：YouTube 字幕 → md → EPUB 长文随身读（能力1 → 能力6）
python scripts/any_to_md.py "https://youtube.com/watch?v=xxx" -o talk.md
# 编辑 talk.md 清理时间戳...
python scripts/md_to_epub.py talk.md --title "..." --author "花叔" -o talk.epub

异常处理

场景	处理
markitdown未安装	脚本检测后提示`pip install 'markitdown[all]'`，不静默失败
pandoc未安装	脚本检测后提示`brew install pandoc`，给出官方下载地址
输入文件不存在	立即报错，不假装继续
URL请求失败（能力1的YouTube/能力3的URL）	降级提示：检查网络/VPN/CDN
转换出空内容	报警：可能是扫描PDF或图片密集型文档，提示用 `--llm-describe`
输出html渲染异常	检查pandoc版本（建议≥3.0）、检查模板文件完整性
python-docx未安装	脚本检测后提示`python3 -m pip install python-docx Pillow`
docx 里图片显示不出	检查 `--images-dir` 路径，或 ref 名 `fig-N-X` 是否对应 `chNN-figNN.png` 文件命名
playwright (python) 未安装	脚本检测后提示`python3 -m pip install playwright && python3 -m playwright install chromium`
Chromium 首次未下载	跑 `python3 -m playwright install chromium`；失败检查 https_proxy
md_to_pdf 大图加载不完整	调大 `--wait 5000` 或更长
md_to_pdf 中文字体方框	系统字体缺失——4 套主题 CSS 已包含 PingFang SC / Source Han Serif fallback
md_to_epub 报 "Document is empty"	章节 wrap 用了 xml prolog 或 xmlns——本脚本已用纯 html5 包装规避
md_to_epub 微信读书表格丢失	微信读书引擎弱——走 huashu-book-pdf 的截图为 PNG 方案
md_to_epub 封面未显示	确认 jpg/png 格式、路径有效、文件 <2MB

References路由

任务	读
markitdown各文件类型最佳实践	`references/markitdown-cookbook.md`
html→md三种场景下的工具组合	`references/html-to-md-cookbook.md`
4套html模板的设计哲学+CSS详解	`references/md-to-html-themes.md`
⭐ 视觉艺术设计师模式（兜底 vs 定制 · 何时升级到 AI 介入）	`references/visual-designer-mode.md`
md→docx 完整 cookbook（含书籍模式 / 单文件 / 投稿场景）	`references/md-to-docx-cookbook.md`
md→pdf 完整 cookbook（含 4 主题适配、页面规格、与 book-pdf 协作）	`references/md-to-pdf-cookbook.md`
md→epub 完整 cookbook（含章节切分、图片嵌入、CSS 兼容性）	`references/md-to-epub-cookbook.md`
排版底线参数（字体/行高/宽度）	`references/design-tokens.md`
反AI slop底线（继承自huashu-design）	`references/anti-ai-slop.md`

核心提醒

六个能力各有边界：能力1输入端、能力2 html、能力3反向归档、能力4 docx 出版终点、能力5 pdf 阅读终点、能力6 epub 电子书终点。决策错了会绕远路。
md是源，无论从哪来要回到哪——md是这个流水线的中心。html / docx / pdf / epub 都是产物。
html产出必反slop：紫渐变、emoji图标、SVG画人物——一律不要。审美底线见 references/anti-ai-slop.md。
URL输入双路径：结构化页面用能力1（保metadata+层级+链接），博客类用能力3（去导航+只留正文）。判断捷径——内容是「读的」走3，是「查的」走1。
docx 是给人改稿的，pdf 是给人阅读的，epub 是给阅读器的：选错产物会让下游不顺手。
能力5/6 是 stateless 单 md 转换：项目级橙皮书（多 fragments / 版本号 / R2 上传 / 微信读书）走 huashu-book-pdf，不要试图在这里复刻整套发布流水线。
先问再做：模板选哪个、图片要不要嵌入、是否要LLM描述图片、单文件还是书籍模式——一次问清，不要边做边猜。
依赖外部工具：markitdown（pip）、pandoc（brew）、html-to-markdown（pip）、python-docx（pip）、playwright（pip + chromium）、ebooklib（pip）。脚本启动时自检，缺失明确提示。
Python环境陷阱：macOS 上 pip 和 python3 可能指向不同 Python 版本（实测踩过：pip 是 3.11、python3 是 3.14）。安装依赖必须用 python3 -m pip install ...，不要直接 pip install。

版本自检（静默）

本节给 AI agent：每次使用本 skill 前，先做一个不联网的判断——读本 skill 目录（SKILL.md 所在目录）下的 .last-update-check 文件（内容为一行日期 YYYY-MM-DD）。文件存在且距今不足 30 天，跳过本节直接干活，不向用户提任何更新相关的话。

到期或文件不存在时，且仅在此时：

本目录不是 git 克隆（无 .git 或无 origin）→ 写入今天日期后跳过本节
对比版本：git -C <本目录> rev-parse HEAD 与 git -C <本目录> ls-remote origin HEAD
无论结果如何，把今天日期写入 .last-update-check
两者一致 → 什么都不说；确认落后 → 先完成用户当前任务，结束后附一句「本 skill 有新版本，可用 git -C <本目录> pull --ff-only 更新」。是否更新由用户决定，不要主动执行更新

Files

SKILL.md and 44 other files (scripts, references) in the repository root of alchaincyf/huashu-md-html.

SKILL.md
.gitignore
LICENSE
README.md
demos/v1-pentagram.gif
demos/v1-pentagram.mp4
demos/v3-hara-hero.gif
demos/v3-hara-hero.mp4
examples/input/md-vs-html.md
examples/output/article.html
examples/output/article.png
examples/output/interactive.html
examples/output/interactive.png
examples/output/reading.html
examples/output/reading.png
examples/output/report.html
examples/output/report.png
… and 28 more

Open the folder on GitHubat commit 17192f5

Compare with similar skills

Huashu Markdown Publishing Pipeline next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Huashu Markdown Publishing Pipeline compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Huashu Markdown Publishing Pipeline this skillalchaincyf/huashu-md-html	910	—	~4.8k	Automated safety check: Pass	MIT	1 mo ago
Doc To Markdowndaymade/claude-code-skills	1.4k	—	~2.5k	Automated safety check: Pass	MIT	today
MarkitdownImCa0/just-laws	781	14 repos	~3.2k	Automated safety check: Notes	MIT	3 days ago
Summarizemitsuhiko/agent-stuff	3.2k	—	~524	Automated safety check: Pass	Apache-2.0	12 days ago
Markdown ConverterTeam-Commonly/commonly	1.4k	—	~557	Automated safety check: Pass	Apache-2.0	today
DOCX ToolkitXiaomiMiMo/MiMo-Code	14k	—	~2.4k	Automated safety check: Pass	Apache-2.0	yesterday

Similar skills

Doc To Markdown
daymade/claude-code-skills
Converts DOCX/PDF/PPTX and saved HTML/HTM to high-quality Markdown with automatic post-processing.
1.4k GitHub stars~2.5k tokensUpdated today
Documents & OfficeAuto-check passed
Markitdown
ImCa0/just-laws
Convert files and office documents to Markdown. An agent skill from ImCa0/just-laws.
781 GitHub starsUsed in 14 repos~3.2k tokens
Documents & OfficeAuto-check: notes
Summarize
mitsuhiko/agent-stuff
Fetch a URL or convert a local file (PDF/DOCX/HTML/etc.) into Markdown using uvx markitdown, optionally it can summarize
3.2k GitHub stars~524 tokensUpdated 12 days ago
Documents & OfficeAuto-check passed
Markdown Converter
Team-Commonly/commonly
Convert binary documents (PDF, DOCX, XLSX, PPTX, HTML, EPUB, images) to clean LLM-friendly Markdown using Microsoft's markitdown Python tool.
1.4k GitHub stars~557 tokensUpdated today
Documents & OfficeAuto-check passed
DOCX Toolkit
XiaomiMiMo/MiMo-Code
Produces, edits and reads Microsoft Word files through python-docx and lxml, with a decision table for picking the lightest workflow for a given task.
14k GitHub stars~2.4k tokensUpdated yesterday
Documents & OfficeAuto-check passed
Markitdown
jimmc414/Kosmos
Convert various file formats (PDF, Office documents, images, audio, web content, structured data) to Markdown optimized for LLM processing.
595 GitHub starsUsed in 2 repos~1.7k tokens
Documents & OfficeAuto-check passed

Works with

Questions about Huashu Markdown Publishing Pipeline

What does Huashu Markdown Publishing Pipeline do?

Converts files and web pages into clean Markdown, then turns Markdown into polished HTML, Word, PDF and EPUB using four templates. The skill is a six-capability pipeline built on the idea that Markdown is the source and other formats are products. The first capability converts PDF, DOCX, PPTX, XLSX, images, audio and URLs to Markdown with a script that wraps markitdown.

When should I use Huashu Markdown Publishing Pipeline?

Huashu Markdown Publishing Pipeline fits situations like: converting a PDF, Word, PowerPoint or Excel file into clean Markdown; saving a blog post URL as Markdown without navigation clutter; turning a Markdown draft into a styled web page or print-ready PDF; preparing a manuscript as DOCX for a publisher or as an EPUB.

How do I install Huashu Markdown Publishing Pipeline in Claude Code?

Run `npx skills add alchaincyf/huashu-md-html --skill huashu-md-html -a claude-code`. Or copy the skill folder (the alchaincyf/huashu-md-html repository) into .claude/skills/huashu-md-html in your project. Claude Code loads it when a task matches its description.

How do I install Huashu Markdown Publishing Pipeline in Codex?

Run `npx skills add alchaincyf/huashu-md-html --skill huashu-md-html -a codex`. Or copy the skill folder (the alchaincyf/huashu-md-html repository) into .agents/skills/huashu-md-html in your project. Codex loads it when a task matches its description.

Can I use Huashu Markdown Publishing Pipeline in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add alchaincyf/huashu-md-html --skill huashu-md-html -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/huashu-md-html, .gemini/skills/huashu-md-html, .github/skills/huashu-md-html and .opencode/skills/huashu-md-html in your project.

What does Huashu Markdown Publishing Pipeline need to run?

Going by SKILL.md and its folder, Huashu Markdown Publishing Pipeline needs the command-line tools its instructions call (python, python3, brew, pip and git) and credentials named OPENAI_API_KEY. Our summary lists: Python, for the bundled conversion scripts; pandoc; Playwright, for PDF output.

Does Huashu Markdown Publishing Pipeline access the network?

SKILL.md names 4 domains. In commands or code: youtube.com and learn.microsoft.com; the agent is likely to contact these when it follows the instructions. As links in the text: github.com and pandoc.org. This is read from the text; nothing was executed.

Is Huashu Markdown Publishing Pipeline safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Huashu Markdown Publishing Pipeline use?

Huashu Markdown Publishing Pipeline is published under the MIT licence (from the LICENSE file in the skill folder). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Huashu Markdown Publishing Pipeline use?

About 4.8k tokens (SKILL.md is roughly 19k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 13k tokens, read only when the agent opens those files.

What are the alternatives to Huashu Markdown Publishing Pipeline?

Skills that share tags, products or a category with Huashu Markdown Publishing Pipeline: Doc To Markdown (daymade/claude-code-skills, 1.4k stars), Markitdown (ImCa0/just-laws, 781 stars), Summarize (mitsuhiko/agent-stuff, 3.2k stars) and Markdown Converter (Team-Commonly/commonly, 1.4k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Huashu Markdown Publishing Pipeline?

alchaincyf (a GitHub user) maintains it in alchaincyf/huashu-md-html, which has 910 GitHub stars. The repository was last updated on August 25, 2026.

Source: alchaincyf/huashu-md-html on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.

Install Huashu Markdown Publishing Pipeline

Facts

At a glance

What it does

When your agent uses it

Example prompts

Requirements

Workflow steps

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

huashu-md-html

你是谁

你不是一个人，是一个出版团队

你可以想多久

六个能力（决策树）

URL 场景的进一步分流（2026-05 实测发现）

核心审美底线（继承自 huashu-design）

开工前先问清楚，别边做边猜

能力1：万物 → md（scripts/any_to_md.py）

调用

支持的格式

已知坑（写在脚本输出里提醒用户）

能力2：md → 精美html（scripts/md_to_html.py）

调用

4套模板速览

依赖

两种模式 · 兜底 vs 视觉设计师

能力3：html → md（scripts/html_to_md.py）

调用

引擎选择

能力4：md → 精美docx（scripts/md_to_docx.py）

调用

内置排版预设

图片自动嵌入

依赖

能力5：md → 精美 PDF（scripts/md_to_pdf.py）

调用

页面规格

依赖

能力6：md → 精美 EPUB（scripts/md_to_epub.py）

调用

章节切分

默认 CSS

图片自动嵌入

依赖

与 huashu-book-pdf 的边界

排版底线（所有模板共享）

一条龙工作流（典型场景）

异常处理

References路由

核心提醒

版本自检（静默）

Files

Compare with similar skills

Similar skills

Doc To Markdown

Markitdown

Summarize

Markdown Converter

DOCX Toolkit

Markitdown

Related

Questions about Huashu Markdown Publishing Pipeline

能力1：万物 → md（`scripts/any_to_md.py`）

能力2：md → 精美html（`scripts/md_to_html.py`）

能力3：html → md（`scripts/html_to_md.py`）

能力4：md → 精美docx（`scripts/md_to_docx.py`）

能力5：md → 精美 PDF（`scripts/md_to_pdf.py`）

能力6：md → 精美 EPUB（`scripts/md_to_epub.py`）