CommonMark や GFM でも説明リストを使いたい

説明リスト (description list) とは、用語と用語の説明をリスト化したものである。

CommonMark や GFM (GitHub Flavored Markdown) では説明リストを Markdown 記法で表現することが出来ない。HTML で表現することは出来るものの少々面倒くさい。これを Markdown のみで疑似的に表現する方法を考えたい。

■ 説明リストと定義リスト

説明リストは次のようなものを指す。（LaTeX から生成）

基本的に、説明リスト (description list) と定義リスト (definition list) は混同され同じものを指していることが多い。

しかしながら、HTML では <dl>・<dt>・<dd> を利用するリストを説明リストと称しており、定義リストではない。一方で、定義リストとして表現するには、<dfn> を利用する必要がある。（HTML4 以前では <dl> を definition list 要素と称されていたが、HTML5 (2014) 以降では description list 要素と称されている）

Markdown 系では、定義リスト (definition list) と称されている。

■ HTML における説明リスト

HTML では、説明リスト (description list) 要素 <dl>、説明用語 (description term) 要素 <dt>、説明詳細 (description details) 要素 <dd> を使うことで説明リストが表現される。

<dt> で示された用語を <dd> で用語の説明している。用語 を太字、用語の説明 をインデントされた行となっている。

<dl>
  <dt>Qiita</dt>
  <dd>エンジニアに関する知識を記録・共有するためのサービス。</dd>
  <dt>Zenn</dt>
  <dd>エンジニアが技術・開発についての知見をシェアする場所。</dd>
</dl>

Qiita: エンジニアに関する知識を記録・共有するためのサービス。
Zenn: エンジニアが技術・開発についての知見をシェアする場所。

これはあくまで 用語 を説明している。定義リストとして表現するには、定義 (definition) 要素 <dfn> を利用する必要があるようだ。

<dl>
  <dt><dfn>Qiita</dfn></dt>
  <dd>エンジニアに関する知識を記録・共有するためのサービス。</dd>
  <dt><dfn>Zenn</dfn></dt>
  <dd>エンジニアが技術・開発についての知見をシェアする場所。</dd>
</dl>

Qiita: エンジニアに関する知識を記録・共有するためのサービス。
Zenn: エンジニアが技術・開発についての知見をシェアする場所。

ただし、Markdown パーサによっては <dfn> タグがサニタイズによって無視されることがある。Qiita では無効化されているようだ。

■ Markdown における定義リスト

Markdown では、定義リストは次のような拡張によって提供されることがある。

markdown-it/markdown-it-deflist: definition list (<dl>) tag plugin for markdown-it markdown parser

文法は Pandoc における definition list に準拠している。

用語
: 用語の説明

HTML では以下のように解釈される。^{[demo source]}

<dl>
<dt>用語</dt>
<dd>用語の説明</dd>
</dl>

しかしながら、これは HTML 的には説明リストである。

■ Markdown で疑似的に表現する

CommonMark に準拠していて markdown-it-deflist などの拡張がない場合、説明リストは HTML で表現するしかない。しかし、HTML で表現するには少し面倒くさい。これを Markdown 記法のみで疑似的に表現したい。

そこで、以下のように番号なしリストを利用する。用語 を太字にしたリスト項目、用語の説明 をリストにネストされたパラグラフによって表現する。

- **用語 1**:

    用語 1 の説明

- **用語 2**:

    用語 2 の説明

用語 1:

用語 1 の説明
用語 2:

用語 2 の説明

もしも、用語の説明に字下げを設けたい場合には、半角スペース ( ) や全角スペース (　) を利用しても良いだろう。HTML 参照エンティティを利用しないとインデントとして認識されるため注意が必要になる。

- **全角スペースでの字下げ**:

    &#12288; `&#12288;` を行頭に挿入

- **半角スペース 4 個での字下げ**:

    &nbsp;&nbsp;&nbsp;&nbsp; `&nbsp;` 4 個を行頭に挿入

全角スペースでの字下げ:

　 　 を行頭に挿入
半角スペース 4 個での字下げ:

  4 個を行頭に挿入

ただし、この字下げはパラグラフ全体の字下げではないため、折り返しが含まれる場合は少し不格好になる。

さいごに

説明リスト使いたい〜

追記

2023/01/26: Markdown での疑似的表現で、**用語** の後ろに : を置くようにしました。