huashu-md-html

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+种格式。 调用 # 基本：自动按扩展名识别 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套精挑模板，覆盖花叔写作场景全部需求。 调用 # 默认：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）。 调用 # 本地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 把这些预设都内置了， 单文件或一整本书都能一条命令生成 。 调用 # 单 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 图片语法： # 内联式：相对路径或绝对路径 ![ 图说 ]( 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 。这个约定让长书（很多章节、几十张图）写起来不用手动维护引用映射。 依赖 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 中转。 调用 # 默认 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 美式法律 依赖 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 控制。