Prototype · Preview: every server in the official registry, synced every 30 minutes. Sign in with Google to write reviews.Prototype · updated every 30 min
PopNx MCPMCP servers for people who use AI · explained in plain words

huashu-md-html Skill

Repository ↗

by alchaincyf★ 9481 skills

Install

What it does

md/html 双向流水线 · 三个能力一站式:万物→md / md→精美html / html→md。封装 markitdown + Pandoc + html-to-markdown + trafilatura。4 套反 AI slop 主题。Claude Code skill.

  • Connects Instruction files the AI reads, with steps that call an outside service
  • Account or key Some steps need a key for OpenAI (per the README)
  • Category Design and web UI
For makers: add a badge to your README

If you made this, paste this code into your README. The badge links back to this page.

[![Featured on PopNx MCP](https://mcp.popnx.com/badge/skill/alchaincyf-huashu-md-html.svg)](https://mcp.popnx.com/en/skills/alchaincyf-huashu-md-html)

Use together with

MCP servers that connect the AI to services for the same work

Next AI Draw.io

draw.io diagrams your AI agent draws on a live browser canvas that you can also edit by hand

by DayuanJiangWidely used↓ 21.7K/wk★ 37K Stars for the whole repoUpdated 5 days ago

MCP · Connects a serviceRuns on your computer

Pascal 3D Editor

Create, inspect, validate, and save editable 3D building scenes with Pascal's MCP server.

by pascalorgWidely used↓ 1K/wk★ 25.6K Stars for the whole repoUpdated yesterday

MCP · Connects a serviceComputer or cloud✓ service owner · pascal.app

Semiotic

Verified React chart generation: select, validate, repair, render, and inspect charts through MCP.

by nteractWidely used↓ 8.5K/wk★ 2.7KUpdated today

MCP · Connects a serviceComputer or cloud

Similar Skills

Same kind of work, ordered like the Skills list

Compared with similar ones
This one
huashu-md-html
impeccablediagram-designfrontend-slidesguizang-ppt-skill
Makeralchaincyfpbakauscathrynlaveryzarazhangruiop7418
Skills11111
GitHub stars948112,54468,06932,51430,030
Last code changeNov 15, 2026Nov 18, 2026Nov 13, 2026Jun 24, 2026Oct 30, 2026
LicenseMITApache-2.0MITMITAGPL-3.0

1 skills (instruction sets) by alchaincyf that an AI reads and follows · not an MCP server

How a Skill differs from MCP

MCP = the hands

Connects the AI to an outside service or data, such as reading Notion or creating an invoice. A program or server has to be running.

Skill = the manual

A text file that teaches the AI how to do a task. It connects to nothing.

Some overlap: a few Skills run scripts that call tools, and a few MCP servers only send knowledge. Start from the task you want done.

Works with

Claude CodeCodexCursor

From the maker’s README and the folders in the repo

Install

Is it safe?

  • Who made it

    GitHub account alchaincyf (person), 3 years old

  • Use and upkeep

    ★ 948 stars · code last changed Nov 15, 2026

  • Any scripts?

    4 scripts that can run on a computer: scripts/any_to_md.py, scripts/html_to_md.py, scripts/md_to_html.py, scripts/md_to_docx.py

  • Uses the internet?

    Scripts that go online: scripts/html_to_md.py

  • Changes machine-wide settings?

    No hooks or writes to machine settings found

Checked automatically from the repo files at commit 0943f0b (read only, nothing was run). Not a safety guarantee: read it and decide for yourself

First: which AI do you use?

Pick your app and this page shows only how to install it there

Option 1Upload to claude.ai (web and app)

This skill is over 5 MB or 300 files, so we do not build a ZIP. Use "Let the AI install it" instead

Option 1Let Claude Code install it

Copy this sentence and paste it into a Claude Code chat

Where to install
Please install the skill huashu-md-html from https://github.com/alchaincyf/huashu-md-html (commit 0943f0b) for all my projects, at ~/.claude/skills/huashu-md-html. First show me every file and tell me whether it has scripts or changes machine settings, then tell me the full path you will install to and wait for me to agree.
Please install the skill huashu-md-html from https://github.com/alchaincyf/huashu-md-html (commit 0943f0b) into the project this chat is open in (at .claude/skills/huashu-md-html). First show me every file and tell me whether it has scripts or changes machine settings, then tell me the project name and the full path you will install to and wait for me to agree.

For one project, paste it into a chat that is open in that project’s folder · The AI always shows you the path before installing

The AI tells you what it will do first and asks your permission at every step

Restart Claude Code, then type /huashu-md-html or ask for a matching task and Claude picks it up

Checked against official docs Nov 12, 2026 · Source: code.claude.com

For Terminal users

A Skill is instructions the AI will follow. Read the files before installing, and install only from makers you trust.

The maker’s recommended way

Install Node.js (if you don’t have it)

Already installed? Check first · Open Terminal, type this command and press Enter

node -v
  • A version number such as v26.13.1 = installed, skip this step
  • "command not found" (on Windows: "is not recognized") = not installed yet, or installed but Terminal needs to be closed and reopened
How to open Terminal

Mac: press ⌘ + Space, type Terminal, press Enter

Windows: open Start, type Windows PowerShell, then Open

Not installed: Open the official download page, pick the LTS version and the click-through installer: .pkg on Mac · .msi on Windows. Double-click and follow it to the end. No curl command needed

Open the Node.js download page ↗

When it’s done, close Terminal, open it again and run the same command. You should see a version number: node -v

Install once; it works for everything that needs Node.js

npx skills add alchaincyf/huashu-md-html

Copied from the maker’s README; it downloads and runs the maker’s code

  1. Open Terminal

    Mac: press Command+Space and type Terminal · Windows: the command below does not work in PowerShell; use “Let AI install it” above instead

  2. Copy the skill folder to ~/.claude/skills

    This downloads the repo to a temporary folder and copies only the folders that contain a SKILL.md

    git clone --depth 1 https://github.com/alchaincyf/huashu-md-html.git /tmp/popnx-skill-alchaincyf-huashu-md-html-0943f0b && mkdir -p ~/.claude/skills && cp -R '/tmp/popnx-skill-alchaincyf-huashu-md-html-0943f0b/.' ~/.claude/skills/huashu-md-html
  3. Restart Claude Code, then type /huashu-md-html or ask for a matching task and Claude picks it up

Skills you install yourself work in the ChatGPT desktop app, Codex CLI and the Codex IDE extension · ChatGPT on the web and mobile cannot use skills you install yourself, only skills that come with a plugin from the directory

ChatGPT desktop app

The ChatGPT desktop app has Codex built in, and Codex reads skills from ~/.agents/skills

Option 1Let ChatGPT install it

Open Codex in the ChatGPT desktop app and paste this sentence into the chat

Where to install
Please install the skill huashu-md-html from https://github.com/alchaincyf/huashu-md-html (commit 0943f0b) for all my projects, at ~/.agents/skills/huashu-md-html. First show me every file and tell me whether it has scripts or changes machine settings, then tell me the full path you will install to and wait for me to agree.
Please install the skill huashu-md-html from https://github.com/alchaincyf/huashu-md-html (commit 0943f0b) into the project this chat is open in (at .agents/skills/huashu-md-html). First show me every file and tell me whether it has scripts or changes machine settings, then tell me the project name and the full path you will install to and wait for me to agree.

The AI always shows you the path before installing

The AI tells you what it will do first and asks your permission at every step

Option 2Put the folder there yourself

Put the huashu-md-html folder at ~/.agents/skills/huashu-md-html

~ is your home folder ($HOME)

For Terminal users

A Skill is instructions the AI will follow. Read the files before installing, and install only from makers you trust.

  1. Open Terminal

    Mac: press Command+Space and type Terminal · Windows: the command below does not work in PowerShell; use “Let AI install it” above instead

  2. Copy the skill folder to ~/.agents/skills

    This downloads the repo to a temporary folder and copies only the folders that contain a SKILL.md

    git clone --depth 1 https://github.com/alchaincyf/huashu-md-html.git /tmp/popnx-skill-alchaincyf-huashu-md-html-0943f0b && mkdir -p ~/.agents/skills && cp -R '/tmp/popnx-skill-alchaincyf-huashu-md-html-0943f0b/.' ~/.agents/skills/huashu-md-html

After installing

  • ChatGPT desktop app: open Skills in the sidebar to see that the skill is there
  • To use it: in ChatGPT type @ and pick the skill · in Codex CLI or the IDE extension run /skills or type $ and the skill name
  • Codex picks up newly installed skills by itself; if one does not show up, restart Codex

Checked against official docs Nov 15, 2026 · Source: learn.chatgpt.com

ChatGPT on the web and mobile

Skills you install yourself do not work here; only skills that come with a plugin from the directory

To use this skill with ChatGPT, use the ChatGPT desktop app as above

Checked against official docs Nov 15, 2026 · Source: learn.chatgpt.com

Option 1Let Codex install it

Copy this sentence and paste it into a Codex chat · Works in Codex inside the ChatGPT desktop app, Codex CLI and the IDE extension

Where to install
Please install the skill huashu-md-html from https://github.com/alchaincyf/huashu-md-html (commit 0943f0b) for all my projects, at ~/.agents/skills/huashu-md-html. First show me every file and tell me whether it has scripts or changes machine settings, then tell me the full path you will install to and wait for me to agree.
Please install the skill huashu-md-html from https://github.com/alchaincyf/huashu-md-html (commit 0943f0b) into the project this chat is open in (at .agents/skills/huashu-md-html). First show me every file and tell me whether it has scripts or changes machine settings, then tell me the project name and the full path you will install to and wait for me to agree.

For one project, paste it into a chat that is open in that project’s folder · The AI always shows you the path before installing

The AI tells you what it will do first and asks your permission at every step

Codex picks up newly installed skills by itself; if one does not show up, restart Codex · To use it: in ChatGPT type @ and pick the skill · in Codex CLI or the IDE extension run /skills or type $ and the skill name

Checked against official docs Nov 15, 2026 · Source: learn.chatgpt.com

For Terminal users

A Skill is instructions the AI will follow. Read the files before installing, and install only from makers you trust.

  1. Open Terminal

    Mac: press Command+Space and type Terminal · Windows: the command below does not work in PowerShell; use “Let AI install it” above instead

  2. Copy the skill folder to ~/.agents/skills

    This downloads the repo to a temporary folder and copies only the folders that contain a SKILL.md

    git clone --depth 1 https://github.com/alchaincyf/huashu-md-html.git /tmp/popnx-skill-alchaincyf-huashu-md-html-0943f0b && mkdir -p ~/.agents/skills && cp -R '/tmp/popnx-skill-alchaincyf-huashu-md-html-0943f0b/.' ~/.agents/skills/huashu-md-html
  3. Restart Codex, then ask for a matching task; Codex lists the skill

Option 1Let Cursor install it

Copy this sentence and paste it into a Cursor chat

Where to install
Please install the skill huashu-md-html from https://github.com/alchaincyf/huashu-md-html (commit 0943f0b) for all my projects, at ~/.cursor/skills/huashu-md-html. First show me every file and tell me whether it has scripts or changes machine settings, then tell me the full path you will install to and wait for me to agree.
Please install the skill huashu-md-html from https://github.com/alchaincyf/huashu-md-html (commit 0943f0b) into the project this chat is open in (at .cursor/skills/huashu-md-html). First show me every file and tell me whether it has scripts or changes machine settings, then tell me the project name and the full path you will install to and wait for me to agree.

For one project, paste it into a chat that is open in that project’s folder · The AI always shows you the path before installing

The AI tells you what it will do first and asks your permission at every step

In Cursor’s Agent chat, type / and pick huashu-md-html

Checked against official docs Nov 12, 2026 · Source: cursor.com

For Terminal users

A Skill is instructions the AI will follow. Read the files before installing, and install only from makers you trust.

  1. Open Terminal

    Mac: press Command+Space and type Terminal · Windows: the command below does not work in PowerShell; use “Let AI install it” above instead

  2. Copy the skill folder to ~/.cursor/skills

    This downloads the repo to a temporary folder and copies only the folders that contain a SKILL.md

    git clone --depth 1 https://github.com/alchaincyf/huashu-md-html.git /tmp/popnx-skill-alchaincyf-huashu-md-html-0943f0b && mkdir -p ~/.cursor/skills && cp -R '/tmp/popnx-skill-alchaincyf-huashu-md-html-0943f0b/.' ~/.cursor/skills/huashu-md-html
  3. In Cursor’s Agent chat, type / and pick huashu-md-html

Option 1Let the AI install it

For other apps that read skills. The sentence gives the paths for Claude Code, Codex and Cursor so the AI picks the one for your app · Copy this sentence into the app’s chat

Where to install
Please install the skill huashu-md-html from https://github.com/alchaincyf/huashu-md-html (commit 0943f0b) for all my projects, at ~/.claude/skills/huashu-md-html (in Codex use ~/.agents/skills/huashu-md-html, in Cursor ~/.cursor/skills/huashu-md-html). First show me every file and tell me whether it has scripts or changes machine settings, then tell me the full path you will install to and wait for me to agree.
Please install the skill huashu-md-html from https://github.com/alchaincyf/huashu-md-html (commit 0943f0b) into the project this chat is open in (at .claude/skills/huashu-md-html; in Codex use .agents/skills/huashu-md-html, in Cursor .cursor/skills/huashu-md-html). First show me every file and tell me whether it has scripts or changes machine settings, then tell me the project name and the full path you will install to and wait for me to agree.

For one project, paste it into a chat that is open in that project’s folder · The AI always shows you the path before installing

The AI tells you what it will do first and asks your permission at every step

Checked against official docs Nov 12, 2026 · Source: code.claude.com, learn.chatgpt.com, cursor.com

For Terminal users

Other apps that support Agent Skills (such as Gemini CLI or GitHub Copilot) use different folders. Check that app’s guide, then copy the folder with the SKILL.md there.

View on GitHub ↗

Skill folders checked against the official Claude Code, Codex and Cursor guides on Nov 11, 2026

✓ Commands checked Nov 18, 2026

View the original SKILL.md

The text below comes from the maker’s repo, not from PopNx MCP

Showing the first 8,000 characters · Open the full file on 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:需要新生成图片、或只做压缩截图的任务。"
metadata:
  author: "花叔"
  homepage: "https://github.com/alchaincyf"
  repository: "https://github.com/alchaincyf/huashu-md-html"
  version: "1.0.1"
---

# 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`。

## 开工前先问清楚,别边做边猜

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

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

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

## 能力1:万物 → md(`scripts/any_to_md.py`)

封装 [microsoft/markitdown](https://github.com/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](https://pandoc.org/) + 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](https://github.com/Goldziher/html-to-markdown)(Rust底层,150-280MB/s)+ [trafilatura](https://github.com/adbar/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](https://github.com/python-openxml/python-docx) + 出版社级排版预设,专为「给人类编辑/出版社审校/投稿/纸质书定稿」场景设计。

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

### 

Discussion

Ask, share a tip or report that it does not work. Sorted by what people marked helpful.

No posts yet. Be the first to ask or share.

Posts here are written by users, not the PopNx team.

Sign in to post

From GitHub

GitHub stars
948
Maker
alchaincyf
License
MIT
Last code change
Nov 15, 2026
SKILL.md files in the repo (including translated copies and templates)
1
Topics
agent-skills, claude-code, claude-code-skills, claude-skills, codex, cursor, document-conversion, epub, html-to-markdown, huashu-skills, markdown, openclaw