huashu-md-html

Q: How to install huashu-md-html?

Create the skills directory: mkdir -p .claude/skills. Then add the config to .claude/skills/huashu-md-html.md. Finally, /huashu-md-html in Claude Code.

Q: What is huashu-md-html best for?

huashu-md-html is categorized under Documentation. It covers: design.

New

GitHub TrendingDocumentationby shf7866

花叔的「md/html双向流水线」skill，三个能力一站式：(1) 用Microsoft markitdown把任意文件（PDF/DOCX/PPTX/XLSX/HTML/图片/音频/YouTube/EPub/ZIP）转成干净的md；(2) 用Pandoc + 4套精挑模板把md加工成出色的html（文章/报告/阅读模式/交互探索），继承huashu-design的反AI slop审美；(3) 用html-to-markdown + trafilatura把html或URL无损转回md。落地花叔的「md生产，html消费」方法论。触发词：md转html、html转md、pdf转md、docx转md、pptx转md、xlsx转md、文件转md、URL转md、文档转md、转markdown、做html、生成html、网页转md、import文档、导入md、导出html、md to html、html to md、any to md、markitdown、pandoc。即使用户只是说「这个PDF变md」「这篇md做成网页」「这个网页存下来」也应触发。

First seen 6/12/2026

Community PluginView Source

Summary

huashu-md-html is a bidirectional pipeline that converts any file (PDF, DOCX, PPTX, XLSX, HTML, images, audio, YouTube, EPub, ZIP) to clean Markdown using Microsoft MarkItDown, transforms Markdown into beautiful HTML with four curated templates and Pandoc, and reverses HTML or URLs back to Markdown via html-to-markdown and Trafilatura.

It enforces huashu-design's anti-AI-slop aesthetic for production-ready documents.

Overview

huashu-md-html

你不再需要亲手编辑产物。md是源代码，html是产物。这个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）
「这个产品页/技术文档URL转md」「带metadata一起拿」	能力1：万物→md（也吃URL）	`scripts/any_to_md.py`

决策原则：能力1产出的md可以直接喂给能力2组成一条龙（如「PDF→精美阅读html」）。能力3用于反向归档（如「把已发布的html博客文章存回项目源」）。

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。

Junior Designer 工作流

收到「转换/美化/导入」类任务时，不要直接执行。先问：

能力是哪个？三选一（用决策树自检）
来源/去向？文件路径 / 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。

能力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。

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

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

code

正文字体（中文）  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
# 看哪个对你下游用途更合适

异常处理

场景	处理
markitdown未安装	脚本检测后提示`pip install 'markitdown[all]'`，不静默失败
pandoc未安装	脚本检测后提示`brew install pandoc`，给出官方下载地址
输入文件不存在	立即报错，不假装继续
URL请求失败（能力1的YouTube/能力3的URL）	降级提示：检查网络/VPN/CDN
转换出空内容	报警：可能是扫描PDF或图片密集型文档，提示用 `--llm-describe`
输出html渲染异常	检查pandoc版本（建议≥3.0）、检查模板文件完整性

References路由

任务	读
markitdown各文件类型最佳实践	`references/markitdown-cookbook.md`
html→md三种场景下的工具组合	`references/html-to-md-cookbook.md`
4套模板的设计哲学+CSS详解	`references/md-to-html-themes.md`
排版底线参数（字体/行高/宽度）	`references/design-tokens.md`
反AI slop底线（继承自huashu-design）	`references/anti-ai-slop.md`

核心提醒

•三个能力是有方向的：能力1输入端、能力2输出端、能力3反向归档。决策错了会绕远路。
•md是源，无论从哪来要回到哪——md是这个流水线的中心。
•html产出必反slop：紫渐变、emoji图标、SVG画人物——一律不要。审美底线见 references/anti-ai-slop.md。
•URL输入双路径：结构化页面用能力1（保metadata+层级+链接），博客类用能力3（去导航+只留正文）。判断捷径——内容是「读的」走3，是「查的」走1。
•Junior先问，再做：模板选哪个、图片要不要嵌入、是否要LLM描述图片——一次问清，不要边做边猜。
•依赖外部工具：markitdown（pip）、pandoc（brew）、html-to-markdown（pip）。脚本启动时自检，缺失明确提示。
•Python环境陷阱：macOS 上 pip 和 python3 可能指向不同 Python 版本（实测踩过：pip 是 3.11、python3 是 3.14）。安装依赖必须用 python3 -m pip install ...，不要直接 pip install。

Install & Usage

Create the skills directory

mkdir -p .claude/skills

Download the skill file

Add the configuration to .claude/skills/huashu-md-html.md

Invoke in Claude Code

/huashu-md-html

Use Cases

Convert a PDF contract to Markdown for version control and editing.

Turn a Markdown blog post into a polished HTML article with publisher-grade typography.

Extract clean Markdown from a web article URL, stripping ads and navigation.

Batch import DOCX and PPTX files from a client into Markdown for a documentation project.

Generate a reading-mode HTML report from a Markdown document with Tufte-inspired styling.

Archive a published HTML page back to Markdown for inclusion in a knowledge base.

Usage Examples

/huashu-md-html Convert this PDF to Markdown

/huashu-md-html Turn my blog post into a beautiful HTML page

/huashu-md-html Extract the main content from this URL as Markdown

View source on GitHub

design

Security Audits

LicenseUnknownSourceWarnRepositoryPass

Frequently Asked Questions

What is huashu-md-html?

How to install huashu-md-html?

To install huashu-md-html: create the skills directory (mkdir -p .claude/skills), then add the config to .claude/skills/huashu-md-html.md. Finally, /huashu-md-html in Claude Code.

What is huashu-md-html best for?

huashu-md-html is a community categorized under Documentation. It is designed for: design. Created by shf7866.

What can I use huashu-md-html for?

huashu-md-html is useful for: Convert a PDF contract to Markdown for version control and editing.; Turn a Markdown blog post into a polished HTML article with publisher-grade typography.; Extract clean Markdown from a web article URL, stripping ads and navigation.; Batch import DOCX and PPTX files from a client into Markdown for a documentation project.; Generate a reading-mode HTML report from a Markdown document with Tufte-inspired styling.; Archive a published HTML page back to Markdown for inclusion in a knowledge base..

Summary

Overview

huashu-md-html

三个能力（决策树）

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

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

Junior Designer 工作流

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

调用

支持的格式

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

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

调用

4套模板速览

依赖

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

调用

引擎选择

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

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

异常处理

References路由

核心提醒

Install & Usage

Use Cases

Usage Examples

Security Audits

Frequently Asked Questions

What is huashu-md-html?

How to install huashu-md-html?

What is huashu-md-html best for?

What can I use huashu-md-html for?

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

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

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