baoyu-markdown-to-html

Markdown 轉 HTML 轉換器

將 Markdown 檔案轉換為內嵌 CSS 的美觀 HTML，專為微信公眾號及其他平台最佳化。

使用者輸入工具

當此技能提示使用者時，請依以下工具選擇規則（優先順序）：

1. 優先使用當前代理執行環境提供的內建使用者輸入工具，例如 AskUserQuestion、request_user_input、clarify、ask_user 或任何等效工具。
2. 備援：若無此類工具，則輸出編號的純文字訊息，要求使用者回覆每個問題的編號/答案。
3. 批次處理：若工具支援單次呼叫多個問題，則將所有適用問題合併為一次呼叫；若僅支援單一問題，則依優先順序逐一詢問。

以下具體的 AskUserQuestion 參考僅為範例 — 請在其他執行環境中替換為當地等效工具。

腳本目錄

代理執行：將此 SKILL.md 所在目錄設為 {baseDir}。解析 ${BUN_X} 執行環境：若已安裝 bun → 使用 bun；若可使用 npx → 使用 npx -y bun；否則建議安裝 bun。將 {baseDir} 和 ${BUN_X} 替換為實際值。

腳本	用途
scripts/main.ts	主要進入點

偏好設定（EXTEND.md）

依優先順序檢查 EXTEND.md — 第一個找到的生效：

優先順序	路徑	範圍
1	.baoyu-skills/baoyu-markdown-to-html/EXTEND.md	專案
2	${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-markdown-to-html/EXTEND.md	XDG
3	$HOME/.baoyu-skills/baoyu-markdown-to-html/EXTEND.md	使用者家目錄

若皆未找到，則使用預設值。

EXTEND.md 支援：預設主題、自訂 CSS 變數、程式碼區塊樣式、Mermaid 預設值（mermaid_theme、mermaid_scale、mermaid_background）。

工作流程

步驟 0：預檢查（中文內容）

條件：僅在輸入檔案包含中文文字時執行。

偵測方式：

1. 讀取輸入的 markdown 檔案
2. 檢查內容是否包含中日韓（CJK）字元
3. 若無 CJK 內容 → 跳至步驟 1

格式建議：

若偵測到 CJK 內容且 baoyu-format-markdown 技能可用：

使用 AskUserQuestion 詢問是否先進行格式化。格式化可修正：

• 粗體標記內含標點符號導致 ** 解析失敗
• CJK 與英文之間的空格問題

若使用者同意：呼叫 baoyu-format-markdown 技能格式化檔案，然後使用格式化後的檔案作為輸入。

若使用者拒絕：繼續使用原始檔案。

步驟 1：決定主題

主題解析順序（第一個符合者勝出）：

1. 使用者明確指定的主題（CLI --theme 或對話中指定）
2. EXTEND.md 中的 default_theme（此技能自身的 EXTEND.md，已在步驟 0 檢查）
3. baoyu-post-to-wechat 的 EXTEND.md 中的 default_theme（跨技能備援）
4. 若皆未找到 → 使用 AskUserQuestion 確認

跨技能 EXTEND.md 檢查（僅在此技能的 EXTEND.md 中沒有 default_theme 時）：

讀取 $HOME/.baoyu-skills/baoyu-post-to-wechat/EXTEND.md（若存在），尋找 default_theme: 行。若有值則使用；否則繼續往下。

若主題從 EXTEND.md 解析得到：直接使用，不詢問使用者。

若未找到預設值：使用 AskUserQuestion 從下方主題表格中確認一個主題。

步驟 1.5：決定引用模式

預設：關閉。預設不詢問。

僅在使用者明確要求「微信外鏈轉底部引用」、「底部引用」、「文末引用」或傳入 --cite 時啟用。

啟用後的行為：

• 一般外部連結會以編號上標呈現，並在最後收集成 引用链接 區段。
• https://mp.weixin.qq.com/... 連結保持為直接連結，不會移至底部。
• 連結文字等於 URL 的裸連結保持內嵌。

步驟 2：轉換

${BUN_X} {baseDir}/scripts/main.ts <markdown_file> --theme <theme> [--cite]

步驟 3：回報結果

從 JSON 結果中顯示輸出路徑。若有建立備份，一併提及。

使用方式

${BUN_X} {baseDir}/scripts/main.ts <markdown_file> [options]

選項：

選項	說明	預設值
--theme <name>	主題名稱（default, grace, simple, modern）	default
--color <name|hex>	主色：預設名稱或十六進位色碼	主題預設
--font-family <name>	字型：sans, serif, serif-cjk, mono 或 CSS 值	主題預設
--font-size <N>	字型大小：14px, 15px, 16px, 17px, 18px	16px
--title <title>	覆蓋 frontmatter 中的標題
--cite	將外部連結轉為底部引用，附加 引用链接 區段	false（關閉）
--keep-title	保留內容中的第一個標題	false（移除）
--mermaid-theme <name>	Mermaid 主題：default, forest, dark, neutral, base	default
--mermaid-scale <N>	Mermaid 渲染縮放比例（正數，≤ 4）	2
--mermaid-width <N>	Mermaid 目標顯示寬度（CSS px）；當圖表窄於此值時，PNG 以 width × scale 像素渲染	860
--mermaid-bg <value>	Mermaid 背景：white, transparent 或 #hex	white
--no-mermaid	跳過 Mermaid PNG 渲染；輸出 <pre class="mermaid"> 備援	false
--help	顯示說明

顏色預設：

名稱	色碼	標籤
blue	#0F4C81	經典藍
green	#009874	翡翠綠
vermilion	#FA5151	鮮紅
yellow	#FECE00	檸檬黃
purple	#92617E	薰衣草紫
sky	#55C9EA	天藍
rose	#B76E79	玫瑰金
olive	#556B2F	橄欖綠
black	#333333	石墨黑
gray	#A9A9A9	煙灰
pink	#FFB7C5	櫻花粉
red	#A93226	中國紅
orange	#D97757	暖橘（modern 主題預設）

範例：

# 基本轉換（使用預設主題，移除第一個標題）
${BUN_X} {baseDir}/scripts/main.ts article.md

# 指定主題
${BUN_X} {baseDir}/scripts/main.ts article.md --theme grace

# 主題搭配自訂顏色
${BUN_X} {baseDir}/scripts/main.ts article.md --theme modern --color red

# 啟用一般外部連結的底部引用
${BUN_X} {baseDir}/scripts/main.ts article.md --cite

# 保留內容中的第一個標題
${BUN_X} {baseDir}/scripts/main.ts article.md --keep-title

# 覆蓋標題
${BUN_X} {baseDir}/scripts/main.ts article.md --title "我的文章"

輸出

檔案位置：與輸入 markdown 檔案相同目錄。

• 輸入：/path/to/article.md
• 輸出：/path/to/article.html

衝突處理：若 HTML 檔案已存在，會先進行備份：

• 備份：/path/to/article.html.bak-YYYYMMDDHHMMSS

JSON 輸出至 stdout：

{
  "title": "文章標題",
  "author": "作者名稱",
  "summary": "文章摘要...",
  "htmlPath": "/path/to/article.html",
  "backupPath": "/path/to/article.html.bak-20260128180000",
  "contentImages": [
    {
      "placeholder": "MDTOHTMLIMGPH_1",
      "localPath": "/path/to/img.png",
      "originalPath": "imgs/image.png"
    }
  ],
  "mermaidImages": [
    {
      "hash": "a1b2c3d4e5f6",
      "localPath": "/path/to/imgs/.mermaid-cache/mermaid-a1b2c3d4e5f6.png",
      "cached": false
    }
  ]
}

Mermaid 渲染：以 ```mermaid 圍欄的程式碼區塊會透過無頭 Chrome（CDP）渲染為 PNG，並快取於 imgs/.mermaid-cache/mermaid-<hash>.png。快取鍵包含程式碼、主題、縮放比例、目標寬度、背景及 mermaid 版本。若不想將產生的圖表納入版本控制，請將 imgs/.mermaid-cache/ 加入 .gitignore。系統需安裝 Chrome/Chromium/Edge；否則區塊會降級為 <pre class="mermaid">…</pre>，轉換仍會成功。

主題

主題	說明
default	經典 - 傳統版面，置中標題帶底部邊框，H2 為白字彩色背景
grace	優雅 - 文字陰影、圓角卡片、精緻引用（by @brzhang）
simple	簡約 - 現代極簡、不對稱圓角、乾淨留白（by @okooo5km）
modern	現代 - 大圓角、藥丸形標題、寬鬆行高（搭配 --color red 可呈現傳統紅金風格）

支援的 Markdown 功能

功能	語法
標題	# H1 至 ###### H6
粗體/斜體	**bold**, *italic*
程式碼區塊	```lang 附語法高亮
行內程式碼	`code`
表格	GitHub 風格的 markdown 表格
圖片	
連結	[text](url)；加上 --cite 可將一般外部連結移至底部參考
引用	> quote
列表	- 無序，1. 有序
警示	> [!NOTE], > [!WARNING] 等
註腳	[^1] 參考
注音標示	`{base
Mermaid	```mermaid 區塊透過無頭 Chrome 渲染為本地 PNG（快取於 imgs/.mermaid-cache/）；若 Chrome 不可用或渲染失敗，則降級為 <pre class="mermaid">
PlantUML	```plantuml 圖表

Frontmatter

支援 YAML frontmatter 作為元資料：

---
title: 文章標題
author: 作者名稱
description: 文章摘要
---

若未找到標題，則從第一個 H1/H2 標題或檔名中提取。

擴充支援

透過 EXTEND.md 進行自訂設定。請參閱偏好設定一節了解路徑及支援的選項。