Markdig 拡張機能

はじめに

このメモ書きは Markdig の続きです。

Markdig には組み込みの拡張機能が用意されており、パイプラインの生成時に提供されている拡張メソッド呼び出せば、該当する拡張機能が有効になります。たとえば Pipe Table を有効にするには

var pipeline = new MarkdownPipelineBuilder()
    .UsePipeTables(); // Pipe Table を有効化
    .Build();

var html = Markdown.ToHtml(markdown, pipeline);

このように書けばよいです。

ほぼ全ての拡張機能を有効にする UseAdvancedExtensions() という拡張メソッドも用意されています。（Emoji, SoftLine as HardLine, Bootstrap, YAML Front Matter, JiraLinks and SmartyPants は有効になりません） Documentation Tests/Specs から各拡張機能の内容を確認できます。

以下ではそれぞれの拡張機能の markdown 書式と変換結果を紹介します。

Pipe Table（パイプテーブル）

テーブルを生成。
左右を | で閉じなくても、いい感じに補完してテーブルを生成してくれます。
シンプルに書きたい人向け。

a  | b 
-- | --
0  | 1 | 2
3  | 4
5  |

a	b
0	1	2
3	4
5

Grid Table（グリッドテーブル）

厳密に行列を記述するタイプのテーブル。
結合セルを作成できます。複雑な表を書く必要がある人向け。

+---+---+---+
| AAAAA | B |
+---+---+ B +
| D | E | B |
+ D +---+---+
| D | CCCCC |
+---+---+---+

AAAAA		B B B
D D D	E
	CCCCC

EmphasisExtra（追加の強調表現）

取り消し線や、下付き、上付き文字など。

The following text ~~is deleted~~

H~2~O is a liquid. 2^10^ is 1024

One quintillionth can be expressed as 10^-18^

Daggers^†^ and double-daggers^‡^ can be used to denote notes.

++Inserted text++

==Marked text==

The following text ~~is deleted~~

H₂O is a liquid. 2¹⁰ is 1024

One quintillionth can be expressed as 10^-18

Daggers^† and double-daggers^‡ can be used to denote notes.

Inserted text

Marked text

Generic Attributes（属性付与）

{ } の中に HTML 要素に付与する属性を指定できます。

# で始める値は id になります。
. で始める値は class になります。
上記以外は key=value 形式で記述することで、そのまま属性になります。

インラインに指定する場合

インラインの直後に改行せずに指定します。

[This is a link](http://google.com){#a-link .myclass data-lang=fr data-value="This is a value"}

以下の HTML に変換されます。

<p><a href="http://google.com" id="a-link" class="myclass" data-lang="fr" data-value="This is a value">This is a link</a></p>

ブロックに指定する場合

ブロックの直前に指定します。

{#fenced-id .fenced-class}
~~~
This is a fenced with attached attributes
~~~

以下の HTML に変換されます。

<pre><code id="fenced-id" class="fenced-class">This is a fenced with attached attributes
</code></pre>

Definition lists（定義リスト）

定義リストを生成します。

<dl> … 定義リスト（Definition List）
<dt> … 用語（Definition Term）
<dd> … 説明（Definition Description）

以下の例だと Term 1、Term 2、Term 3 が <dt> タグに、: 以降が <dd> タグに変換されます。

Term 1
:   This is a definition item
    With a paragraph
    > This is a block quote

    - This is a list
    - with an item2

    ```java
    Test


    ```

    And a last line
:   This ia another definition item

Term 2
Term 3 *with some inline*
:   This is another definition for term2

Term 1

This is a definition item With a paragraph

This is a block quote

This is a list
with an item2

Test

And a last line

This ia another definition item

Term 2

Term 3 with some inline

This is another definition for term2

Footnotes（脚注）

脚注の内容はドキュメントの末尾（変換した HTML の一番最後）に追加されます。

Here is a footnote reference,[^1] and another.[^longnote]

This is another reference to [^1]

[^1]: Here is the footnote.

And another reference to [^longnote]

[^longnote]: Here's one with multiple blocks.

    Subsequent paragraphs are indented to show that they
belong to the previous footnote.

    > This is a block quote
    > Inside a footnote

        { some.code }

    The whole paragraph can be indented, or just the first
    line.  In this way, multi-paragraph footnotes work like
    multi-paragraph list items.

This paragraph won't be part of the note, because it
isn't indented.

Here is a footnote reference,¹ and another.²

This is another reference to ¹

And another reference to ²

This paragraph won't be part of the note, because it isn't indented.

Auto-identifiers（id 自動生成）

見出しに id 属性を自動付与します。目次の作成などに使えます。
見出しのテキストをもとに id を付与しますが、重複しないようにしてくれます。

# This is a heading
# This is a heading

以下のように変換されます。

<h1 id="this-is-a-heading">This is a heading</h1>
<h1 id="this-is-a-heading-1">This is a heading</h1>

TaskLists（タスクリスト）

チェックボックス付きのリスト。

- [ ] Item1
- [x] Item2
- [ ] Item3

Item1
Item2
Item3

Media support（動画）

Youtube などのプレイヤー付き動画リンクを生成できます。

![youtube.com](https://www.youtube.com/watch?v=mswPy5bt3TQ)

![youtube.com/embed 2](https://www.youtube.com/embed?listType=playlist&list=PLC77007E23FF423C6)

![vimeo](https://vimeo.com/8607834)

![ok.ru](https://ok.ru/video/26870090463)

Abbreviations（略語）

略語と正式名称を定義できます。
以下の例では、略語 HTML の上にマウスカーソルをのせるとツールチップで正式名称の Hypertext Markup Language が表示されます。

*[HTML]: Hypertext Markup Language

Later in a text we are using HTML and it becomes an abbr tag HTML

Later in a text we are using HTML and it becomes an abbr tag HTML

Figure、Footer、Cite

<figure> と <figcaption> タグ、<footer> タグ、<cite> タグを生成します。

<figure> … 図形を囲むためのタグ。<figcaption> タグで説明を付けることができます。
<footer> … フッター。
<cite> … 出典や参照先を表すタグ。

※ブラウザによりますが、これらのタグには独自のスタイルがない（cite は文字が斜めになります）ので、見た目は特に変わりません。HTML に意味（セマンティクス）を与えるためにあります。

^^^
This is a figure
^^^ This is a *caption*

^^ This is a footer
^^ multi-line

This is a ""citation of someone""

以下のような HTML に変換されます。

<figure>
<p>This is a figure</p>
<figcaption>This is a <em>caption</em></figcaption>
</figure>

<footer>This is a footer
multi-line</footer>

<p>This is a <cite>citation of someone</cite></p>

Custom containers

:::[クラス名] <内部コンテンツ> ::: で <内部コンテンツ> を囲む <div class="[クラス名]"></div> タグを生成します。

:::spoiler
This is a *spoiler*
:::

以下のような HTML に変換されます。

<div class="spoiler"><p>This is a <em>spoiler</em></p>
</div>

いろいろな用途がありますが、たとえば独自の css と組み合わせて特定の箇所だけ枠線で囲む、文字の色やスタイルを変える、といったことが実現できます。

Mathematics（LaTeX 記法の有効化）

LaTeX 数式記法を使用できるようになります。
LaTeX をレンダリングする JavaScript ライブラリが別途必要になります。（このページでは MathJax を使用）

This is a $E = mc^2$

$$
\begin{equation}
  \int_0^\infty \frac{x^3}{e^x-1}\,dx = \frac{\pi^4}{15}
  \label{eq:sample}
\end{equation}
$$

This is a \(E = mc^2\)

\[ \begin{equation} \int_0^\infty \frac{x^3}{e^x-1}\,dx = \frac{\pi^4}{15} \label{eq:sample} \end{equation} \]

Soft lines as hard lines（改行で `<br>` 挿入）

Markdown では改行しても、生成される HTML は改行されない、つまり <br> が挿入されません（Soft line）。通常は文末に半角スペースを2個以上入れると改行されます（Hard line）が、この拡張機能を有効にすると改行しただけで <br> が挿入されるようになります。

This is a paragraph
with a break inside

This is a paragraph
with a break inside

Emoji（ショートコードで絵文字を挿入）

絵文字ショートコードを使用して絵文字を挿入できるようになります。

This is a test with a :) and a :angry: :smiley:

This is a test with a 😃 and a 😠 😃

Diagrams（図を描く）

テキスト記法でフローチャートやシーケンス図などの図を描けるようになります。
現時点で対応しているのは以下の２つのライブラリ。

以下は Mermeid の例。

```mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
```

graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

脚注

Here is the footnote.↩↩
Here's one with multiple blocks.

Subsequent paragraphs are indented to show that they belong to the previous footnote.

This is a block quote Inside a footnote
```
{ some.code }
```
The whole paragraph can be indented, or just the first line. In this way, multi-paragraph footnotes work like multi-paragraph list items.↩↩

目次