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 になる。

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

インラインの直後に指定する。

[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>

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\)

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（図を描く）

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

• Mermaid
• nomnoml

以下は Mermeid の例。

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

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