本記事では、Markdown 記法の中でもあまり知られていない、ニッチな記法についていくつか紹介します。

はじめに

Markdown とは、軽量なマークアップ言語¹です。Web ページやドキュメントの作成など、さまざまな場面で広く利用されています。Qiita でも技術記事を作成する際に使用されています。

Markdown の仕様はさまざま存在します。CommonMark と CommonMark を拡張した GitHub Flavored Markdown (GFM) が有名です。

Qiita の Markdown 記法 は基本的には GFM に準拠し、一部を独自に拡張しています（改行の扱いなど、完全に準拠しているわけではありません）。

本記事では、以下の仕様とそのバージョンに基づいて解説を行います。

CommonMark: 0.31.2(2024-01-28)

その理由は、多くの Markdown パーサー²で CommonMark やそれを拡張した GFM の仕様が採用されているためです。

Qiita の Markdown の基本的な記法に興味がある場合は Markdown記法チートシート #Qiita - Qiita を確認してください。

隠しテキスト

ブラウザ上で表示したくない文章がある場合、HTML のコメントアウトを使用することで隠すことができます。

<!--
隠したいテキスト 
-->

` をコードスパンで囲む

コードスパン（<code></code>）を使用するためには、コードスパンで囲みたいテキストの前後に 1 つ以上のバックティック（`）で囲む必要があります。

しかし、バックティック（`）自体をコードスパンで囲みたい場合、```と記述しても期待通りに変換されません。

コードスパン内にバックティック（`）自体を含めたい場合、そのバックティックの数と異なる数のバックティック（`）で囲む必要があり、また、コードスパンで囲みたいテキストの前後にスペースが必要です。

Markdown

`` ` ``

HTML

<code>`</code>

Markdown

` ``コードスパン`` `

HTML

<code>``コードスパン``</code>

参照元: Code spans

段落内で改行

CommonMark では、段落内に改行を挿入する方法は2種類あります。

Soft Line Breaks
通常の改行文字（\n、\r、\r\n）を使用して改行を挿入する方法です。
この場合、パーサーで HTML 形式に変換される際にもそのまま改行文字として残ります。しかし、Web ブラウザ上では、改行がスペースに変換されたように表示されます。
```
foo
bar
```
上記のように記述した場合、ブラウザ上では foo bar のように表示されます。
Hard Line Breaks
ブラウザ上でも改行を明示的に表示したい場合はこの方法を使用します。
HTML 形式に変換されるときには、<br> タグとして表示されます。
この方法を使用するためには、行末にスペースを 2 つもしくはバックスラッシュを追加します。
```
foo\
bar
```
これにより、ブラウザ上でも foo と bar が別々の行として表示されます。
```
foo
bar
```

参照元: Hard line breaks -CommonMark

Qiita では、改行の扱いに関して、完全に CommonMark に準拠しているわけではないため、一部挙動が異なります。

詳細

Qiita では、CommonMark の仕様と異なり、foo と bar の間に改行（\n: Soft line breaks）を挿入すると、Web ブラウザ上では下記のように表示されます。

foo
bar

上記の文書が Qiita の Markdown パーサーにより、以下のように HTML に変換されているためです。

Qiita Parser

<p>foo<br />bar</p>

CommonMark 準拠の Markdown パーサーでは以下のように変換されるため、

CommonMark Parser

<p>foo
bar</p>

Web ブラウザ上では通常、以下のように表示されます。

foo bar

ただし、行末にスペースを 2 つもしくはバックスラッシュ追加した場合、

foo\
bar

Qiita のパーサーでも CommonMark 準拠のパーサーでも以下のように変換されます。

Qiita Parser

<p>foo<br />
bar</p>

見出しを
複数行
にする

見出しには　ATX heading (# で始まる) と Setext heading (= もしくは - の行が段落に続く) の 2 種類ありますが、見出しを複数行にしたい場合は、Setext heading を使用し、行末にスペースを 2 つもしくはバックスラッシュを追加する必要があります。

Setext heading の特性上、見出し 1 もしくは 見出し 2 のみ可能です。

以下のように記述すると、

Markdown

見出し 1 (h1) を\
複数列\
にする
=

見出し 2 (h2) を\
複数列にする
-

HTML に変換する Markdown パーサーは以下を生成します。

HTML

<h1>見出し 1 (h1) を<br />
複数列<br />
にする</h1>

<h2>見出し 2 (h2) を<br />
複数列にする</h2>

Qiita では、Setext heading を使用する必要はありますが、行末にスペースを 2 つもしくはバックスラッシュを追加する必要はありません。

コードブロック内に ```

コードブロックを使用する場合、3 つのバッククオート（```）で囲むことは有名です。しかし、コードブロック内に ``` を記述したい場合は、上記の方法ではできません。

（いくつか方法はありますが、）3 つ以上チルダ（~）で囲むことで可能になります。

~~~
```
~~~

コードブロック内に ``` と ~~~ 両方を記述したい場合は、３つ以上のバッククオート（`）またはチルダ（~）で囲みます。

````
```
~~~
````

ちなみに、コードブロック（Fenced code blocks）をMarkdownで記述する際の基本的なルールは以下の通りです。

3 つ以上の連続したバッククオート（`）またはチルダ（~）を使用する
開始と終了の特殊文字（` またはチルダ ~）は同じ種類である必要がある
終了の特殊文字の数は開始の特殊文字の数以上である必要がある

参照元: Fenced code blocks - CommonMark

自動リンク

URLや電子メールアドレスを < と > で囲むと、CommonMark はそれを自動的にリンクとして認識します。参照元: Autolinks - CommonMark

<https://example.com>
<email@example.com>

※ Qiita では、< と > で囲まなくても、自動的にリンクとして認識します。

https://example.com
email@example.com

エスケープ文字

Markdown の記法に使用されている特殊文字をテキストとして表示したい場合は、バックスラッシュ（\）を使います。

以下の例では、アスタリスク(*)をエスケープしています。

Markdown

\*emphasis*

HTMLに変換する Markdown パーサーでは、以下のように変換されます。

HTML

<p>*emphasis*</p>

Web ブラウザ上では、エスケープされた文字は通常のテキストとして表示されます。

*emphasis*

ただし、バックスラッシュ（\）自体をバックスラッシュ（\）でエスケープすると

Markdown

\\*emphasis*

特殊文字（* や _ など）はエスケープされません。

HTML

<p>\<em>emphasis</em></p>

参照元: Backslash escapes - CommonMark

おわりに

CommonMark は非常に柔軟で強力な Markdown 仕様です。基本的な記法だけでなく、この記事で紹介したニッチな記法を活用することで、より表現力豊かなドキュメントを作成することができます。Markdownを使う際には、これらの記法をぜひ試してみてください。

マークアップ言語とは、構造（見出し、段落など）や装飾（リンク、強調など）を指定するために使用される規則です。例: HTML、Markdown、LaTeX ↩
Markdown パーサーとは、Markdown の仕様に従って記述されたテキストを解析し、その構造や内容を理解して、別の形式（例えば HTML）に変換するプログラムやライブラリのことを指します。 ↩