zenn-markdown-html 0.2.11 → 0.2.12-alpha.0

package/lib/index.d.ts

@@ -1,4 +1,15 @@
 import { MarkdownOptions } from './types';
-declare const markdownToHtml: (text: string, options?: MarkdownOptions) => string;
+/**
+ * Markdown を HTML に変換する（非同期）
+ *
+ * Shiki によるシンタックスハイライトを使用。
+ * 詳細なアーキテクチャについては md-renderer-fence.ts のコメントを参照。
+ *
+ * 処理フロー:
+ * 1. [Phase 1] md.render() - Markdown を HTML に変換（コードブロックはプレースホルダーに）
+ * 2. [Phase 2 & 3] applyHighlighting() - プレースホルダーをハイライト済み HTML に置換
+ * 3. sanitize() - XSS 対策のためサニタイズ
+ */
+declare const markdownToHtml: (text: string, options?: MarkdownOptions) => Promise<string>;
 export default markdownToHtml;
 export { markdownToSimpleHtml } from './markdown-to-simple-html';

package/lib/index.js

@@ -27,13 +27,25 @@ var _mdImage = require("./utils/md-image");
 var _mdContainer = require("./utils/md-container");
 var _markdownToSimpleHtml = require("./markdown-to-simple-html");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-// plugis
+// plugins
 
 const mdContainer = require('markdown-it-container');
 const mdFootnote = require('markdown-it-footnote');
 const mdTaskLists = require('markdown-it-task-lists');
 const mdInlineComments = require('markdown-it-inline-comments');
-const markdownToHtml = (text, options) => {
+
+/**
+ * Markdown を HTML に変換する（非同期）
+ *
+ * Shiki によるシンタックスハイライトを使用。
+ * 詳細なアーキテクチャについては md-renderer-fence.ts のコメントを参照。
+ *
+ * 処理フロー:
+ * 1. [Phase 1] md.render() - Markdown を HTML に変換（コードブロックはプレースホルダーに）
+ * 2. [Phase 2 & 3] applyHighlighting() - プレースホルダーをハイライト済み HTML に置換
+ * 3. sanitize() - XSS 対策のためサニタイズ
+ */
+const markdownToHtml = async (text, options) => {
   if (!(text && text.length)) return '';
   const markdownOptions = {
     ...options,
@@ -53,7 +65,10 @@ const markdownToHtml = (text, options) => {
     fuzzyEmail: false
   }); // refs: https://github.com/markdown-it/linkify-it
 
-  md.use(_mdBr.mdBr).use(_mdKatex.mdKatex).use(mdFootnote).use(mdInlineComments).use(_markdownItImsize.default).use(_mdLinkAttributes.mdLinkAttributes).use(_mdCustomBlock.mdCustomBlock, markdownOptions).use(_mdRendererFence.mdRendererFence, markdownOptions).use(_mdLinkifyToCard.mdLinkifyToCard, markdownOptions).use(mdTaskLists, {
+  // コードブロック情報を保存する配列
+  // Phase 1 で mdRendererFence によって追加され、Phase 2 でハイライト処理に使用される
+  const codeBlocks = [];
+  md.use(_mdBr.mdBr).use(_mdKatex.mdKatex).use(mdFootnote).use(mdInlineComments).use(_markdownItImsize.default).use(_mdLinkAttributes.mdLinkAttributes).use(_mdCustomBlock.mdCustomBlock, markdownOptions).use(_mdRendererFence.mdRendererFence, markdownOptions, codeBlocks).use(_mdLinkifyToCard.mdLinkifyToCard, markdownOptions).use(mdTaskLists, {
     enabled: true
   }).use(mdContainer, 'details', _mdContainer.containerDetailsOptions).use(mdContainer, 'message', _mdContainer.containerMessageOptions).use(_markdownItAnchor.default, {
     level: [1, 2, 3, 4],
@@ -73,8 +88,25 @@ const markdownToHtml = (text, options) => {
   // - https://github.com/zenn-dev/zenn-community/issues/356
   // - https://github.com/markdown-it/markdown-it-footnote/pull/8
   const docId = _crypto.default.randomBytes(2).toString('hex');
-  return (0, _sanitizer.sanitize)(md.render(text, {
+
+  // ============================================================
+  // Phase 1: Markdown → HTML 変換（同期）
+  // ============================================================
+  // markdown-it がコードブロックを検出すると mdRendererFence が呼ばれ、
+  // コードブロック情報が codeBlocks 配列に保存され、
+  // HTML にはプレースホルダー（<!--SHIKI_CODE_BLOCK_xxxxxxxx-->）が挿入される
+  const rawHtml = md.render(text, {
     docId
-  }));
+  });
+
+  // ============================================================
+  // Phase 2 & 3: シンタックスハイライト適用（非同期）
+  // ============================================================
+  // - Phase 2: 全コードブロックを Shiki で並列ハイライト
+  // - Phase 3: プレースホルダーをハイライト済み HTML に置換
+  const highlightedHtml = await (0, _mdRendererFence.applyHighlighting)(rawHtml, codeBlocks);
+
+  // サニタイズして返す（XSS 対策）
+  return (0, _sanitizer.sanitize)(highlightedHtml);
 };
 var _default = exports.default = markdownToHtml;

package/lib/sanitizer.js

@@ -33,10 +33,10 @@ const attributes = {
   li: ['class', 'id', 'data-line'],
   ol: ['class', 'start', 'data-line'],
   p: ['class', 'data-line'],
-  pre: ['class'],
+  pre: ['class', 'style'],
   s: [],
   section: ['class', 'data-line'],
-  span: ['class', 'title'],
+  span: ['class', 'style', 'title'],
   strong: [],
   summary: [],
   sup: ['class'],

package/lib/utils/highlight.d.ts

@@ -1 +1,48 @@
-export declare function highlight(text: string, langName: string, hasDiff: boolean): string;
+/**
+ * Shiki によるシンタックスハイライト処理
+ *
+ * このモジュールは Phase 2（applyHighlighting）から呼び出され、
+ * 個々のコードブロックをハイライトする役割を持つ。
+ *
+ * ## 特徴
+ *
+ * - シングルトン: ハイライターインスタンスは1つだけ作成され再利用される
+ * - 遅延ロード: 言語定義は初回使用時にのみロードされる
+ * - diff サポート: ベース言語のハイライト + diff 背景色の両方を適用
+ * - transformers: Shiki の transformers API で AST レベルの変換を実行
+ *
+ * ## 関連ファイル
+ *
+ * - `md-renderer-fence.ts`: Phase 1（収集）と Phase 3（置換）
+ * - `index.ts`: 全体の統合
+ */
+import { Highlighter } from 'shiki';
+/**
+ * Shiki ハイライターを初期化する
+ * 最初は最低限のセットで初期化し、必要に応じて言語をロードする
+ */
+export declare function getHighlighter(): Promise<Highlighter>;
+/**
+ * ハイライトオプション
+ */
+export interface HighlightOptions {
+    /** diff モードかどうか */
+    hasDiff: boolean;
+    /** 追加するクラス名 */
+    className: string;
+    /** Markdown ソースの行番号（ソースマップ用） */
+    line?: number;
+}
+/**
+ * [Phase 2 の実処理] コードをハイライトする
+ *
+ * applyHighlighting() から各コードブロックに対して呼び出される。
+ * 言語が未ロードの場合は自動的にロードする（遅延ロード）。
+ * Shiki の transformers API を使用して AST レベルで変換を行う。
+ *
+ * @param text - ハイライト対象のコード文字列
+ * @param langName - 言語名（例: "javascript", "python"）
+ * @param options - ハイライトオプション
+ * @returns ハイライト済み HTML（常に <pre><code> 構造）
+ */
+export declare function highlight(text: string, langName: string, options: HighlightOptions): Promise<string>;