baoyu-markdown-to-html

Markdown から HTML への変換

Markdown ファイルを、WeChat 公式アカウントやその他のプラットフォーム向けに最適化された、インライン CSS 付きの美しくスタイル設定された HTML に変換します。

ユーザー入力ツール

このスキルがユーザーに質問する場合は、次の優先順位に従ってツールを選択してください。

1. 組み込みのユーザー入力ツールを優先する — 例：現在のエージェントランタイムが提供する AskUserQuestion、request_user_input、clarify、ask_user など。
2. フォールバック：そのようなツールがない場合は、番号付きのプレーンテキストメッセージを出力し、質問ごとに選択した番号または回答を返信するようユーザーに依頼します。
3. まとめて質問する：1 回の呼び出しで複数の質問に対応できる場合は、該当する質問をすべてまとめて呼び出します。1 回に 1 つの質問しかできない場合は、優先順位に従って 1 つずつ質問します。

以下の 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>	メインカラー：プリセット名または16進数値	theme default
--font-family <name>	フォント：sans、serif、serif-cjk、mono、またはCSS値	theme default
--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の描画倍率（0より大きく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	ヘルプを表示します

カラープリセット：

名前	16進数	ラベル
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のデフォルト）

使用例：

# Basic conversion (uses default theme, removes first heading)
${BUN_X} {baseDir}/scripts/main.ts article.md

# With specific theme
${BUN_X} {baseDir}/scripts/main.ts article.md --theme grace

# Theme with custom color
${BUN_X} {baseDir}/scripts/main.ts article.md --theme modern --color red

# Enable bottom citations for ordinary external links
${BUN_X} {baseDir}/scripts/main.ts article.md --cite

# Keep the first heading in content
${BUN_X} {baseDir}/scripts/main.ts article.md --keep-title

# Override title
${BUN_X} {baseDir}/scripts/main.ts article.md --title "My Article"

出力

ファイルの場所：入力Markdownファイルと同じディレクトリです。

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

競合時の処理：HTMLファイルがすでに存在する場合、最初にバックアップされます。

• バックアップ：/path/to/article.html.bak-YYYYMMDDHHMMSS

標準出力へのJSON出力：

{
  "title": "Article Title",
  "author": "Author Name",
  "summary": "Article 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	エレガント - テキストシャドウ、角丸カード、洗練された引用（@brzhangによる）
simple	ミニマル - モダンでミニマルなデザイン、非対称の角丸、すっきりとした余白（@okooo5kmによる）
modern	モダン - 大きな角丸、ピル型のタイトル、ゆったりとした行間（伝統的な赤と金のスタイルには --color red を組み合わせてください）

対応するMarkdown機能

機能	構文
見出し	# H1 から ###### H6
太字／斜体	**bold**、*italic*
コードブロック	シンタックスハイライト付きの ```lang
インラインコード	`code`
表	GitHub Flavored Markdown形式の表
画像	
リンク	[text](url)。通常の外部リンクをページ下部の参照に移動するには --cite を追加します
引用	> quote
リスト	- は順序なし、1. は順序付き
アラート	> [!NOTE]、> [!WARNING] など
脚注	[^1] 参照
ルビ	`{base
Mermaid	```mermaid ブロックはヘッドレスChromeを使ってローカルPNGに描画されます（imgs/.mermaid-cache/ にキャッシュ）。Chromeが利用できない場合、または描画に失敗した場合は <pre class="mermaid"> にフォールバックします
PlantUML	```plantuml 図

フロントマター

メタデータ用の YAML フロントマターに対応しています。

---
title: Article Title
author: Author Name
description: Article summary
---

タイトルが見つからない場合は、最初の H1／H2 見出しから抽出するか、ファイル名を使用します。

拡張機能のサポート

EXTEND.md を使用してカスタム設定を行えます。パスとサポートされているオプションについては、設定セクションを参照してください。