remark によるブログ記事の Markdown 処理

remark に限らずどの Markdown ライブラリもそうだと思いますが、出力される HTML の各要素は基本的に class 属性が付きません。しかし本ブログでは独自拡張として、例えばリストは通常の順不同リストのほかに「リンクリスト」や「注釈リスト」を追加しているため、 <ul> 要素が複数の使われ方をしており、クラスで区別する必要があります。

remark で Markdown を元に HTML を生成する場合、以下のようにいったん抽象構文木（AST）を経由して変換を行います。

1. 【パーサー】 Markdown → Markdown 構文木 (mdast)
2. 【トランスフォーマー】 Markdown 構文木 (mdast) → HTML 構文木 (hast)
3. 【コンパイラー】 HTML 構文木 (hast) → HTML

これを図で表すとこうなります。（remark が内部で使用している unifiedのドキュメントより引用）

| ........................ process ........................... |
| .......... parse ... | ... run ... | ... stringify ..........|

          +--------+                     +----------+
Input ->- | Parser | ->- Syntax Tree ->- | Compiler | ->- Output
          +--------+          |          +----------+
                              X
                              |
                       +--------------+
                       | Transformers |
                       +--------------+

<ul> 要素にクラスを追加する場合、Markdown の - をリスト（list）と認識するところは remark のパーサーが行ってくれるため、トランスフォーマー（mdast → hast）の部分をカスタマイズすることになります。具体的には以下のように、remark-rehypeの handlers オプションにハンドラー関数を登録します。

import rehypeStringify from 'rehype-stringify';
import remarkParse from 'remark-parse';
import remarkRehype from 'remark-rehype';
import { unified } from 'unified';

const processor = unified();
processor.use(remarkParse); // Markdown → mdast
processor.use(remarkRehype, {
	handlers: {
		list: (state, node, parent) => {
			if (node.ordered) {
				/* <ol> の処理（省略） */
			} else {
				/* <ul> の処理 */
				return {
					type: 'element',
					tagName: 'ul',
					properties: {
						className: ['my-list'],
					},
					children: state.all(node),
				};
			}
		},
		foo: (state, node, parent) => {
			/* リスト以外の処理も行う場合はこのように追加してゆく */
		}
	},
}); // mdast → hast
processor.use(rehypeStringify); // hast → HTML

const html = await processor.process(`
- list
`);

console.debug(html.value); // <ul class="my-list"><li>list</li></ul>

上記コードはクラスを付与するだけの単純なものですが、先祖や子孫に要素を追加したり、親要素（parent）によって条件を分岐したりするといった複雑なことも可能です。

• 実際に本ブログでカスタマイズしている要素

通常、Markdwon は # を <h1>、## を <h2> といったように見出しのみを出力します。しかし HTML5 ではせっかく <section> 要素があるのですから、それを活用したいところです。

2022年にアウトラインアルゴリズムが廃止されたため <section> 要素を使用しても文書のアウトラインには影響を及ぼさず、また WAI-ARIA との関連からしても <section> 要素はデフォルトロール（暗黙のARIAセマンティックス）を持たないため、そこまで躍起になる必要はありませんが、セクションを要素で囲むことで CSS によるスタイル付けが容易になりますし、なによりセクションがセクションであることをユーザーに伝えるメリットは捨てがたいものです。

remark には多数のプラグインがあり、remark-sectionizeのようにこれを実現できるものもすでに存在します。しかし本ブログでは見出しに関して以下のような処理を行っています。

• 見出しと後続のコンテンツを <section> 要素で囲う
• セクションに ID を設定する（id 属性は <hn> 要素でなく <section> 要素に書き出す）
• 記事タイトル（<h1> 要素）は本文には含めないため、Markdown の見出し階層と HTML の見出しレベルは一つずらす（# は <h2>、## は <h3> とする）
• 目次を自動生成する（挿入位置は文書冒頭ではなく最初の # の直上とする）

個々の機能はプラグインが存在するものの、目次の挿入位置など細かな調整を含めてこれらをすべて実現するプラグインは見つからなかったので自作することにしました。

• 見出しに ID を付与 （id 属性は最終的に <section> 要素に出力するが、処理の都合上 mdast の時点では見出しに ID を設定する）
• <section> 要素を使用
• 目次の自動生成

<ul> 要素にクラスを設定した事例で紹介したように、出力される HTML は簡単にカスタマイズ可能です。しかし唯一(?)の例外が脚注で、これは決め打ちで出力されてしまいます。

脚注は Markdown の標準では存在しないため、remark-gfmを追加で読み込み、以下の Markdown を変換します。

HTML[^1]とは……

[^1]: [HTML Standard](https://html.spec.whatwg.org/multipage/)

すると、出力される HTML はこうなります。（改行やインデントは実際とは多少異なります）

<p>HTML<sup><a href="#user-content-fn-1" id="user-content-fnref-1" data-footnote-ref aria-describedby="footnote-label">1</a></sup>とは……</p>

<section data-footnotes class="footnotes">
	<h2 class="sr-only" id="footnote-label">Footnotes</h2>

	<ol>
		<li id="user-content-fn-1">
			<p>
				<a href="https://html.spec.whatwg.org/multipage/">HTML Standard</a>
				<a href="#user-content-fnref-1" data-footnote-backref class="data-footnote-backref" aria-label="Back to content">↩</a>
			</p>
		</li>
	</ol>
</section>

このうち、参照リンク: sup > a[data-footnote-ref] の部分は footnoteReference の名前で構文木に存在するため、前記の <ul> と同じ要領でカスタマイズ可能です。

一方、脚注そのもの: section[data-footnotes] は mdast-util-to-hast/lib/footer.jsでの管理となっており、remark-rehype のオプションでカスタマイズする形になります。

processor.use(remarkRehype, {
	clobberPrefix: 'my-footnote',
	footnoteLabel: '脚注',
	footnoteLabelTagName: 'h2',
	footnoteLabelProperties: {
		className: ['footnote-heading'],
	},
	footnoteBackLabel: 'コンテンツへ戻る',
	handlers: {
		// 省略
	},
}); // mdast → hast

これで見出し周りはだいぶカスタマイズできるのですが、<section> のクラスや <ol> の中身はほとんど変えることができません。

とくに気になるのがリストに <ol> 要素を採用していることです。 <ol> 要素とは

とあるように、順序に意味があるリストであり、機械の操作手順や料理のレシピのようなケースに使うものです。

脚注のリストは本文中に登場した参照リンクを末尾にまとめているだけで、このリスト自体は順序に意味を持ちません。仮に順序を変更したとして、HTML 仕様に書かれているような「順序を変更することで文書の意味が変わる」ことはありません。そのため、ここに <ol> を採用するのは適切ではなく、<ul> が妥当でしょう。あるいは <dl> でも良いと思います。

前述のとおり通常のやり方で <ol> 要素の変更ができないため、hast の構築後にむりやり構造を書き換える形となります。以下に挙げるコードは <ol> の要素名を <ul> に書き換えるだけの単純な処理ですが、完成された DOM を自分好みに変更するユーザースクリプトのような感覚で任意の構造に組み直すことも可能です。

import { select } from 'hast-util-select';

// 中略

processor.use(remarkRehype, {
	// 省略
}); // mdast → hast

processor.use(() => {
	return (tree) => {
		/* 脚注のカスタマイズ */
		const footnoteList = select('[data-footnotes] > ol', tree);
		if (footnoteList === null) {
			return;
		}
		footnoteList.tagName = 'ul';
	};
});

• 実際に本ブログでカスタマイズしている脚注

<table> や <dl> は既存の拡張構文を import して登録すればよいのですが、本ブログ独自に採用したものも多くあります。

完全に独自の概念としては、以下のようなものがあります。とくに <blockquote> にするほどでもないワンフレーズの引用として <q> 要素を使用する頻度は多く、なぜこれが Markdown に存在しないのか不思議なくらいです。

また既存の構文を拡張したものの一例を挙げます。

remark は Lint 機能も充実しており、Markdown の構文チェックを行うことができます。

例えば <em> と <strong> はそれぞれアスタリスク構文とアンダースコア構文がありますが、Markdown Guide(www.markdownguide.org)ではアスタリスク構文をベストプラクティスとしているため、アンダースコア構文が使用されていた場合は警告を出すようにします。

import remarkLintEmphasisMarker from 'remark-lint-emphasis-marker';
import remarkLintStrongMarker from 'remark-lint-strong-marker';

// 中略

const processor = unified();

processor.use(remarkLintEmphasisMarker, '*'); // <em> の構文チェック
processor.use(remarkLintStrongMarker, '*'); // <strong> の構文チェック

processor.use(remarkParse); // Markdown → mdast
processor.use(remarkRehype); // mdast → hast
processor.use(rehypeStringify); // hast → HTML

const emAsterisk = await processor.process('I like *kinoko*.');
console.debug(emAsterisk.value); // <p>I like <em>kinoko</em>.</p>
console.debug(emAsterisk.messages); // []

const emUnderscore = await processor.process('I like _takenoko_.');
console.debug(emUnderscore.value); // <p>I like <em>takenoko</em>.</p>
console.debug(emUnderscore.messages); // [ { reason: 'Emphasis should use `*` as a marker', ... } ]

公式からリンクが張られているものだけでも 100近いルールが存在しますが、足りないものは自作することもできます。

本ブログでは以下のような独自のチェックを行っています。

• 見出し階層のリミットを設定（3階層目の ### 以深は警告する）
• セクション内に見出し以外のコンテンツが存在すること（# heading1\n# heading2 のようなケースを警告する）
• <br> や <hr> などいくつかの構文は使用しない
• Loose list は使用しない[6]
• [Duck Duck Go](https://duckduckgo.com "The best search engine for privacy") のようなリンクのタイトルは使用しない[7]
• HTML タグ表記は `<p>` のように極力コード構文内に書く（ただし引用時は引用元の表現を尊重し、意図的に素のまま書くこともある）

• 実際に本ブログで導入している独自の Lint 機能