L1-09：Markdown转网页 —— 格式转换型 Skill 的设计公式

🎯 学什么：格式转换型 Skill 的通用设计公式——「解析输入格式 → 应用转换规则 → 渲染输出格式」。同时学习两个重要的设计判断：展示型 vs 数据型输出（什么时候需要主题/样式系统）、以及跨 Skill 偏好共享（一个 Skill 可以读取另一个 Skill 的 EXTEND.md）。 💡 难易度：⭐ | ⏱️ 预计时间：40 分钟

---

1. 课程概览

💡 白话小课堂：格式转换就像翻译——但不是翻译语言，是翻译格式。把 Markdown（Markdown：用简单符号如 # = 标题来排版的纯文本格式，是写文档的通用语言） 翻译成 HTML（HTML/超文本标记语言：网页的骨架，定义页面内容和结构） 网页、把 CSV 翻译成 JSON（JSON：轻量级数据交换格式，人和机器都易读写，互联网数据传输的事实标准） 数据。L1-09 的 baoyu-markdown-to-html 是一个典型的格式转换型 Skill——它把你的 Markdown 文章变成带 CSS（CSS/层叠样式表：控制网页外观的语言，决定颜色、字体、布局） 样式的网页，能直接嵌入微信公众号、CMS 后台、Email 模板里。核心设计逻辑极简：解析 → 转换 → 输出。

本课与 L1-03 的关系——一个格式化，一个转换：

🔑 核心秘诀：格式转换型 Skill 的设计公式只有三步——解析输入、应用规则、渲染输出。但两个判断决定了 Skill 的质量：一是输出给谁看（人需要主题，机器不需要），二是目标平台有什么特殊限制（微信不准放外部链接 → 设计 --cite 模式）。

⚠️ 避坑指南：不要太快判断一个格式转换「太简单不用学」——baoyu-markdown-to-html 虽然只做一件事，但包含了跨 Skill 偏好共享（读 baoyu-post-to-wechat 的 EXTEND.md）、平台适应性设计（微信外链规则）、增值功能标注（KaTeX/Mermaid 作为区分于同类工具的卖点）——这些都是可以推广到任何 Skill 的设计技巧。

---

2. 格式转换型通用公式详解

2.1 三步公式

所有格式转换型 Skill 都遵循同一个公式：

格式转换 = 解析输入格式 → 应用转换规则 → 渲染输出格式

示例 1：Markdown → HTML
  解析：读取 .md 文件 → 识别标题/加粗/代码块/表格等 Markdown 语法
  应用规则：标题 # → <h1>，加粗 ** → <strong>，代码块 → <pre><code>
  渲染：嵌入 CSS 样式 → 输出 .html 文件

示例 2：CSV → JSON
  解析：读取 .csv 文件 → 识别表头行和数据行 → 处理逗号转义
  应用规则：表头列名 → JSON key，每行数据 → JSON value，数字列 → 类型转换
  渲染：JSON.stringify() → 输出 .json 文件

示例 3：YAML → JSON
  解析：读取 .yaml 文件 → 解析缩进层级关系
  应用规则：YAML 层级结构 → JSON 嵌套对象
  渲染：JSON.stringify() with indentation → 输出 .json 文件

🔑 一句话总结：格式转换 Skill 的本质不是「创造内容」，而是「翻译格式」。输入和输出的信息相同，只是表示方式不同。

2.2 关键判断：输出给谁看？

这是格式转换 Skill 设计中第一个也是最关键的判断——它决定了是否需要样式/主题系统：

展示型输出（给人看）：
  Markdown → HTML 网页        ✓ 需要主题（颜色/字体/间距）
  Markdown → PPT 演示文稿      ✓ 需要主题（配色/版式）
  Markdown → PDF 报告          ✓ 需要主题（排版/页眉页脚）
  Markdown → 图片卡片          ✓ 需要主题（风格/布局/配色）

  判断标准：输出会被「人类眼睛」阅读 → 视觉美感影响体验
  → 必须提供主题/样式系统

数据型输出（给机器读）：
  CSV → JSON                   ✗ 不需要主题
  Markdown → 纯文本            ✗ 不需要主题
  JSON → YAML                  ✗ 不需要主题
  XML → JSON                   ✗ 不需要主题

  判断标准：输出被「程序/机器」消费 → 格式正确性 > 视觉美感
  → 完全不需要主题/样式系统

🔑 设计要点：baoyu-markdown-to-html 提供 4 种主题（default/grace/simple/modern）不是过度设计——HTML 输出是给人看的，不同场景需要不同视觉风格。但如果是 CSV→JSON 的格式转换 Skill 也提供 4 种主题，那就是严重过度设计。

2.3 baoyu-markdown-to-html 的完整流程

Step 0: 中文内容预检
  → 检测输入是否含中文
  → 如果有中文 + baoyu-format-markdown Skill 可用
  → 建议用户先用 baoyu-format-markdown 格式化（修正加粗符号、中英文间距）
  → 这是「跨 Skill 协作」——格式转换前先格式修正，保证输入质量

Step 1: 确定主题
  → 优先级：用户 CLI 参数 > EXTEND.md > baoyu-post-to-wechat EXTEND.md > 询问用户
  → 4 种主题：default（经典）/ grace（优雅）/ simple（极简）/ modern（现代）
  → 可选自定义：颜色（13 种预设）、字体（sans/serif/mono）、字号（14-18px）

Step 1.5: 确定引用模式
  → 默认关闭。只在用户明确要求时才启用
  → --cite 模式：普通外链 → 编号上标 + 文末"引用链接"章节
  → 微信公众号链接保持原样不动
  → 裸链接（链接文本=URL）保持原样

Step 2: 执行转换
  → ${BUN_X} scripts/main.ts 

<div class="feishu-attachment-card"><strong>未命名附件</strong><span>FILE · 搬运后会在文章底部生成下载入口</span><code>unknown</code></div>

--theme <name> [--cite]

Step 3: 报告结果
  → 显示输出路径
  → 如有冲突（同名 HTML 已存在），提示备份路径

2.4 增值功能：区分于同类工具的卖点

baoyu-markdown-to-html 支持一些不是所有 Markdown→HTML 工具都有的功能：

🔑 设计要点：增值功能不能喧宾夺主——KaTeX 和 Mermaid 是「加分项」不是「核心功能」，在 description 中简要提一句就够了，不需要在 Skill 的主流程中详细展开。但如果用户恰好有这些需求，增值功能就是你选择 baoyu-markdown-to-html 而不是其他同类工具的理由。

---

3. 主题系统与偏好管理 —— 让一次设置永久生效

3.1 主题优先级链

用户不需要每次转换都选择主题——Skill 内置了 4 级主题查找链：

Level 1: 命令行参数（临时覆盖）
  ${BUN_X} main.ts article.md --theme modern
  → 最高优先级，本次生效

Level 2: 本 Skill 的 EXTEND.md（持久偏好）
  .baoyu-skills/baoyu-markdown-to-html/EXTEND.md
  或 ${XDG_CONFIG_HOME}/baoyu-skills/baoyu-markdown-to-html/EXTEND.md
  或 ~/.baoyu-skills/baoyu-markdown-to-html/EXTEND.md
  → 用户设过一次，每次自动用

Level 3: 兄弟 Skill 的 EXTEND.md（跨 Skill 共享）
  ~/.baoyu-skills/baoyu-post-to-wechat/EXTEND.md
  → 如果用户在用「发微信公众号」Skill，说明有发布偏好，直接复用

Level 4: 询问用户（兜底）
  AskUserQuestion：「请选择主题：default / grace / simple / modern」
  → 都没找到，问就行了

🔑 设计亮点：Level 3（跨 Skill 偏好共享）是一个精妙的设计决策——baoyu-markdown-to-html 会去读 baoyu-post-to-wechat 的 EXTEND.md。为什么？因为如果你在用「Markdown 转 HTML → 发布到微信」这条链路，你的主题偏好大概率跟发布偏好一致。让 Skill 之间「互相理解」而不是「各自为政」，减少重复设置。

3.2 EXTEND.md 的配置项

# .baoyu-skills/baoyu-markdown-to-html/EXTEND.md


default_theme: modern     # 默认主题
custom_css: |             # 自定义 CSS 变量
  --primary-color: #FA5151
  --font-family: "Noto Serif CJK SC"
code_block_style: dark    # 代码块样式

EXTEND.md 的三级查找：

🔑 设计要点：项目级 > 用户级的优先级让「团队协作」成为可能——项目的 .baoyu-skills/ 目录里放团队统一的主题配置，团队成员 clone 项目后自动用统一的主题。个人偏好用 $HOME/.baoyu-skills/，不影响团队其他人。

3.3 4 种主题对比

3.4 颜色预设系统

主题定义了布局和字体，但颜色可以独立调整。13 种预设颜色让用户不需要记 Hex 值：

🔑 设计要点：颜色预设解决的是「我知道要红色但不记得 Hex 值是 #FA5151 还是 #A93226」的问题。让用户用语义化的名字（--color red）而不是记数字。这跟 L1-06 的 Preset 预设（knowledge-card → notion + dense）是同一个设计思路——降低用户的认知门槛。

---

4. 平台适应性设计 —— 微信外链规则的案例研究

4.1 问题：为什么需要 --cite 模式？

微信公众号的文章正文中，外部链接有一个坑：点击外链会跳转到浏览器而非在微信内打开。这让读者体验很差——点了一个链接，突然跳到浏览器，然后可能就回不来了。

但你又不能完全不放链接——有些信息确实需要引用来源。

4.2 解决方案：底部引用模式

baoyu-markdown-to-html 的 --cite 模式是这样处理的：

原始 Markdown（有外部链接）：
  根据 [Google 的研究](https://research.google.com/...) 显示……
  更多信息请查看 [官方文档](https://docs.example.com)。
  直接在微信内阅读 [这篇](https://mp.weixin.qq.com/s/xxx)。

--cite 转换后：
  根据 Google 的研究[1] 显示……
  更多信息请查看 官方文档[2]。
  直接在微信内阅读 [这篇](https://mp.weixin.qq.com/s/xxx)。  ← 微信公众号链接保持原样

  ---
  ## 引用链接
  [1] https://research.google.com/...
  [2] https://docs.example.com

三条处理规则：

1. 普通外链 → 移除链接，改为编号上标 [N]，文末集中列出
2. 微信公众号链接（mp.weixin.qq.com）→ 保持原样不处理（微信内链接可以正常跳转）
3. 裸链接（链接文字 = URL）→ 保持原样不处理（这种链接本身就是给人复制的）

🔑 设计要点：--cite 模式的精妙之处在于默认关闭——只有用户明确说「我要发微信」时才启用。如果默认开启，那些不需要发微信的用户会被这个行为困惑（「我的链接怎么全跑到底部了？」）。这就是「默认行为应该对最大多数用户友好，特殊行为应该显式触发」原则。

4.3 平台适应性作为通用设计模式

平台适应性的通用模式：

1. 识别目标平台的特殊限制/规则
   微信：不准直接放外链
   微博：140 字限制
   小红书：图片数量限制

2. 设计一个可选的适应模式
   --cite、--shorten、--split-images

3. 模式默认关闭，用户明确触发时才启用
   避免「我以为你要发微信，但其实你要发 Email」的尴尬

4. 模式的行为有清晰的边界和文档
   哪些链接会被转？哪些保持原样？为什么？

---

5. 结构拆解：格式转换型 Skill 模板

从 L1-09 提取「格式转换型」Skill 的通用模板——这是 Level 1 的第七种模式。

格式转换型 vs 其他架构：

---

6. 电商案例：多规格SKU商品详情页——Markdown模板一键转HTML

🛒 实战案例：某家居灯具店铺在淘宝有80个SKU，每个产品有3-5个规格变体（颜色×尺寸×功率）。产品详情页用Markdown在Obsidian里写（方便版本管理和团队协作），但发布到淘宝详情需要HTML格式。此前每次改一个SKU的详情，要在Markdown和HTML之间手动转换——复制到在线转换器→粘贴回淘宝后台→检查格式→修复错乱，一个SKU耗时20分钟，80个SKU就是26小时。

用 baoyu-markdown-to-html 实现一键转换发布：

1. 源文件管理：产品经理用Markdown写详情页——规格表格（颜色×尺寸×功率×价格）、场景展示图、安装说明、售后政策——全部存在Git仓库，每次修改可追溯
2. 一键转HTML：选用 grace 主题（暖色调契合灯具品类）、--color amber 琥珀色强调
3. 规格表自动渲染：Markdown表格自动转为HTML表格，合并单元格、斑马纹行——3种颜色×3种尺寸×2种功率=18行规格一目了然
4. 图片自动嵌入：Markdown中的本地图片路径自动转为CDN链接
5. 批量输出：80个SKU一次性转换，输出 {sku-id}.html，直接复制到淘宝旺铺详情编辑器

效果：

• 80个SKU详情页格式转换：26小时（手动）→ 30秒（一键批量）——省了整整一个人3天的工作量

• 格式一致性100%——脚本保证，不会出现"这个SKU的表格多了一列、那个SKU的图片没对齐"

• 版本控制：折扣季临时改价/改规格，Git记录每次修改，运营和设计不再互相甩锅"谁改的"

• 多规格变体页面模板化：新增一个SKU，复制Markdown模板改3个变量（品名、功率、价格），一键出HTML

🔑 启示：电商详情页最大的效率黑洞不是"写"而是"转"——Markdown写起来快但发不出去，HTML能发但改起来痛苦。格式转换Skill让团队各用各的舒适区：产品经理用Markdown写和改，脚本负责Markdown→HTML的"翻译"，谁也不妥协。

---

7. 变体练习

设计一个「JSON → Markdown 表格」的 Skill：

• 输入：JSON 数组
• 输出：Markdown 表格
• 可选：自动检测列宽、对齐方向

思考题：

1. 根据格式转换型通用公式，这个 Skill 的三步分别是什么？
2. 这个 Skill 需要主题系统吗？为什么？
3. JSON 输入如果不合法（比如缺少字段或类型不匹配），Skill 应该怎么处理？

点击查看思路

1. 三步：解析输入（JSON.parse()，提取数组和数据字段）→ 应用转换规则（表头 = 对象的 keys，每行 = 对象 values，数字列右对齐、文本列左对齐）→ 渲染输出（生成 Markdown 表格字符串）。

2. 不需要主题系统——输出是 Markdown 表格，最终渲染样式由目标阅读器（Obsidian/GitHub/Typora 等）决定，不是 Skill 的职责。强行内嵌样式反而限制了用户的自由度。

3. 错误处理：输入不合法时优雅降级——不直接崩溃，而是报告具体问题（「第 3 行缺少 price 字段」「第 7 行的 quantity 不是数字」），让用户修复后重试。同时提供 --skip-errors 选项跳过错误行继续处理。

---

8. 掌握检验

Q1：格式转换型 Skill 的通用公式是什么？

• A) 收集数据 → 清洗数据 → 可视化数据
• B) 解析输入格式 → 应用转换规则 → 渲染输出格式
• C) 识别意图 → 生成代码 → 执行脚本
• D) 检测内容类型 → 分析结构 → 生成摘要

Q2：以下哪种转换场景需要提供主题（如 default、grace、simple），哪种不需要？判断标准是什么？

• A) 所有格式转换都需要主题
• B) 展示型输出（如 Markdown→HTML 给人看）需要主题，数据型输出（如 CSV→JSON 给机器读）不需要
• C) 输入是 Markdown 的才需要主题，输入是其他格式的不需要
• D) 只有 Web 相关的格式转换才需要主题

Q3：baoyu-markdown-to-html 的主题优先级链包含哪四个级别？为什么 Level 3 要读 baoyu-post-to-wechat 的 EXTEND.md？这个设计解决了什么问题？

Q4：baoyu-markdown-to-html 的 --cite（微信外链转底部引用）模式默认是什么状态？为什么设计为默认关闭而非默认开启？

Q5：以下哪项是 baoyu-markdown-to-html 的「增值功能」而非「必须功能」？

• A) 将 Markdown 转为 HTML
• B) 输出带有基本样式的 HTML
• C) 数学公式渲染（KaTeX）和 Mermaid 图表支持
• D) 解析 Markdown 语法

Q6：某家居电商有 500 个产品页，用 Markdown 管理源文件、用 HTML 发布到 Shopify。这种「Markdown 写作 + HTML 发布」的组合解决了哪两个核心矛盾？为什么用 Git 管理 Markdown 源文件比直接管理 HTML 文件更好？

Q7：如果要设计一个「CSV → JSON」的格式转换 Skill，根据通用公式，你需要定义哪三个核心部分？这个 Skill 需要主题系统吗？为什么？

---

9. 答案

点击查看答案

Q1：B — 格式转换型 Skill 的通用公式是"解析输入格式 → 应用转换规则 → 渲染输出格式"。Markdown→HTML 就是解析 MD 语法、应用 HTML 渲染规则、嵌入 CSS 样式。CSV→JSON 就是解析 CSV 行、映射为 JSON 数组、序列化输出。A 描述的是数据处理流水线，C 描述的是代码生成模式，D 描述的是内容分析模式（接近 L1-03）。

Q2：B — 判断标准是「输出给谁看」：展示型输出（给人看，如 HTML 网页、PDF 报告）需要主题来提供视觉美感；数据型输出（给机器读，如 CSV→JSON、YAML→JSON）不需要主题，因为机器不关心颜色和字体。A 太绝对，C 和 D 的判断标准不对——关键不是输入格式类型，而是输出的受众。

Q3：四级优先级链：1) 命令行参数（临时覆盖，最高优先级）；2) 本 Skill 的 EXTEND.md（持久偏好，项目级 > 用户级）；3) baoyu-post-to-wechat 的 EXTEND.md（跨 Skill 偏好共享）；4) AskUserQuestion 询问用户（兜底）。Level 3 读 baoyu-post-to-wechat 的 EXTEND.md 的设计逻辑是：如果你在用「Markdown 转 HTML → 发布到微信」这条链路，你的主题偏好大概率跟发布偏好一致。这解决了跨 Skill 协作中的「重复设置」问题——用户不需要在两个 Skill 里分别设置同样的主题偏好。「让你的 Skills 互相理解」比「让它们各自为政」要好。

Q4：--cite 模式默认关闭。原因：如果默认开启，那些不需要发微信的用户会被这个行为困惑（「我的链接怎么全跑到底部了？」）。只有用户明确说「我要发微信」或传入 --cite 参数时才启用。这是「默认行为对最大多数用户友好，特殊行为显式触发」原则的体现——跟 L1-07 的 Consent Check（危险功能必须显式同意）是同一个逻辑。

Q5：C — 数学公式渲染（KaTeX）和 Mermaid 图表支持是增值功能——不是所有的 Markdown 都有公式和图表，但对于有这些需求的用户，这是这个 Skill 区别于其他 Markdown→HTML 工具的独特卖点。A/B/D 都是格式转换的核心必须功能。

Q6：两个核心矛盾：1) 「写」和「看」的格式不统一——Markdown 是最适合人类写作的格式（简洁、纯文本），HTML 是最适合浏览器展示的格式（样式丰富、响应式），格式转换 Skill 让团队不需要在两者间妥协。2) 「效率」和「质量」的冲突——手工转格式慢（500 个页面手动做一个完整工作日），但自动化后格式一致性 100%。用 Git 管理 Markdown 源文件比直接管理 HTML 更好是因为：Markdown 是纯文本，Git diff 能精确显示每次修改的内容（哪一行改了什么词）；而 HTML 的 diff 充满了样式标签的噪音，根本看不出实质性修改。Git + Markdown = 产品描述的可追溯版本历史。

Q7：三个核心部分：1) 输入格式解析——解析 CSV 文件的行和列，处理逗号分隔、引号转义、表头行；2) 转换规则——将 CSV 行映射为 JSON 对象数组（表头作为 key，每行数据作为 value），处理数字类型自动转换、空值处理等；3) 输出渲染——将 JSON 数组序列化为标准的 JSON 字符串输出。这个 Skill 不需要主题系统，因为 JSON 是给机器读取的数据格式，不是给人看的展示格式——机器不关心颜色和字体，只关心键值对的正确性。

（6/7 通过）

---

10. 延伸阅读

• [[L1-10-弹窗转化率优化|下一课：弹窗转化率优化]] — 进入营销转化型 Skill
• [[L1-03-Markdown格式化排版|L1-03：Markdown格式化]] — 回顾「格式修正 vs 格式转换」的本质区别
• [[L1-06-图文卡片制作|L1-06：图片卡片]] — 另一个通过 EXTEND.md 管理偏好的 Skill