CommonMarkの仕様とか

CommonMarkとは

• Markdownの仕様が全然決まってないのにキレた人達で作った軽量マークアップ言語

Github Flavored Markdownで良くない？

• 大本のMarkdownそのものはもう仕様が決まることはない
• CommonMarkは仕様を決めることがメイン、拡張はまた別の話
• CommonMarkが標準になって、GFMがGFCになるのが理想的

具体的なCommonMarkの仕様は？

• CommonMark Spec(2016/11/18時点の最新はver.0.27)
• 書き方の仕様をメインとして、細かな解釈とか内部仕様以外を以下に挙げる
• ついでにBoostnoteでの解釈が違う場合はその仕様も載せる（自分用）
• Google翻訳と英単語拾って読んでるので色々間違ってるかもしれない
• 項番はCommonMark Specと一致しない

1. タブ

• Tab、または半角スペース4つでコードブロックになる
  • BoostnoteではTab2つ、または半角スペース6つ

    foo
    bar
    baz

• リストや引用の後に入れるとそのリストや引用の中にコードブロックが作られる

-    foo
>    bar

2. ブロックとインライン

• 常にブロック構造（リストとか引用とか）がインライン構造より優先されるよ
• 下の例だとfooとbarはバッククォートで囲まれてるけど、ハイフンが先にあるからそっちが優先

- `foo
- bar`

3. 罫線

• -（ハイフン）と*（アスタリスク）を3つ書いた行は罫線になる
• 3つ以上書いても罫線になるけど、2つ以下だと当然罫線にならないよ
• スペースは入ってもいいけど文字は入っちゃ駄目
• ハイフンとアスタリスクをまぜこぜにするのも駄目

---
***

4. 見出し

• #（井桁）の後に半角スペースを入れると、その後の文字列が見出しになる
• #～##### がそれぞれ <h1>～<h5> に当たる、1つか2つの時は直後に罫線が入る
• #の後に文字があると見出しにならないからハッシュタグとかも書けるよ
• シャープじゃねぇよ

# foo
## foo
### foo
#### foo
##### foo

5. 罫線付き見出し

• 文字列の次の行に=（イコール）か-（ハイフン）があると、文字列が見出しになる
• =か-の行は罫線になる、=と-の数はいくつでもいい
• =は<h1>、-は<h2>の見出しになる

foo
=
bar
-

• 次の例の場合はfooとbarが見出し、bazが次の段落になる
• fooとbarを別にしたいなら改行してね

foo
bar
---
baz

6. フェンス付きコードブロック

• 3つの`(バッククォート)か~(チルダ)で囲まれた部分はコードブロックになるよ
• 生成されるタグ(<pre><code>～</code></pre>)はタブと同じ
  • Boostnoteでは`か~2つ以下で囲むとタブと同じ、3つ以上で囲むと行番号付きコードブロックになる

    ```
    foo
    ```

    ~~~
    bar
    ~~~

• Qiita（GFMの仕様？）だと異なる記号で囲んでも解釈がおかしい、めんどい

7. HTML

• いい感じに解釈します（実際はちゃんと仕様がありますが細かいので割愛）

8. リンク

• 下の構文でリンクの定義ができて、[foo]と記載するとそこがリンクになる
• 定義と[foo]はどっちが先に来ても大丈夫、定義を下とか上にまとめられるよ
• 'title'の部分は省略してもいい、その時はfooがリンクの名前になるよ
  • Boostnoteではローカルファイルのパスをurlに書いても開いたり出来ないみたい

    [foo]:url 'title'
    [bar]:url

• CommonMarkの仕様として、リンクのURLはURLパーセントエンコーディングされる
• ローカルパスだとバックスラッシュがエンコーディングされてしまうので、パスが成立しなくなる
• ローカルファイルをリンクにしたいときは直接HTMLタグを使えばエンコーディングされないよ
  • 実行ファイルをリンクしたい時はexeの直接実行は出来ないので、batにしようね

<a href=”localpath”>foo</a>

9. 段落

• 空白行があるとそこが前の段落と後ろの段落の境目になる

foo
bar

baz

• 空白行の次が見出しやリストだと空白行は無視されるよ

foo

# bar

10. ブロック引用

• >(大なり)を書くとそれ以降の文章が引用になる
• >の後に空白がなくても大丈夫、但し>の前は半角スペースか行の先頭でないと駄目

> foo
> bar

• リストや罫線を挟まない場合、>の後は>を省略しても引用になるよ

> foo
bar

• 段落をまたいで引用にしたい時は、空白行に>が必要だよ

> foo
> 
> bar

11. 箇条書きリスト

• -(ハイフン)、+(プラス)、*(アスタリスク)のいずれかでそれ以降の文章がリストになる
• どの記号でも直後に半角スペースが必要、ないと普通の文章になる
• 前の行と次の行で記号が違う場合はそれぞれ別のリスト扱いになるよ

- foo
+ bar
* baz

• 前の行がリストの場合、次の行のインデントが一致すると同じリスト内の別段落になる

- foo
  bar
  baz

• リストには見出しが含められるよ
• 半角スペース2つずつ追加していくとリストを入れ子に出来るよ

- # title
  - aaa
    - bbb
      - ccc

• リストの解釈における詳細な仕様は原文読んでね（複雑な上にかなり細かい）

12. 順序付きリスト

• 数字と.(コンマ)か)(右小括弧)で順序付きリストになる
• 数字は9桁まで、負の値は駄目、0から始まって良い、また前ゼロ付きでも良い
  • Boostnoteだと数字がなんであっても自動的に付番し直してくれる
  • 一番最初の数字に＋1ずつされていく
• その他の仕様は箇条書きリストとほぼ同じ

1. foo
2. bar
3. baz

1) foo
2) bar
3) baz

• リストの入れ子をする場合、順序付きでは数字が2桁以上の場合は半角スペースが4つ必要
  • Boostnoteでは順序付きの場合、常に半角スペースが4つ必要

10. foo
    11. bar

13. バックスラッシュ

• いつも通り\(バックスラッシュ)で記号のエスケープが出来るよ
• ついでに行の最後にバックスラッシュがあると明確な改行(<br />)になるよ

\# foo
\- bar\
\> baz

14. エンティティ参照と数値参照

• HTMLで解釈されるエンティティ参照と数値参照はその通りに解釈される
• エンティティ参照はHTML5に準拠してるよ

  & © Æ Ď
¾ ℋ ⅆ
∲ ≧̸
# Ӓ Ϡ � �

15. 強調

• *(アスタリスク)か_(アンダースコア)で文字列を囲むと強調出来る
• 1つで斜体、2つで強調(<strong>)出来る
  • Boostnoteでは3つで斜体＋強調になる
  • CommonMarkの仕様なのかBoostnote独自なのか微妙、Markdownの仕様に近くはある

*aaa*
**bbb**
_ccc_
__ddd__

• 記号の数を3つ以上にすると強調の度合いが増す
• 上記以外の詳細な仕様は原文読んでね（リストより複雑かつ詳細）

16. インラインリンク

• リンクの省略版、以下の構文でリンクになるよ
• リンクと同じでtitleは省略出来る

[foo](url "title")
[foo](url)

• 入れ子を含めた上記以外の詳細な仕様は原文読んでね

17. 画像

• リンクまたはインラインリンクの先頭に!(エクスクラメーションマーク)を付けると<img>になる
• 他の仕様はリンク、インラインリンクと同じ
  • Boostnoteではリンクと同じで画像を表示は出来ないみたい

![foo](url "title")
![bar]

    [bar]:url 'title'

• ローカルの画像を表示させたい時はリンクと同じでHTMLタグ使ってね

<img src=”localpath”/>

18. オートリンク

• <(小なり)と>(大なり)で囲むとそのままリンクになる
• 半角スペースが入るとリンクにならなくなるので注意が必要

<http://foo.com/bar>

• HTML5の仕様として使われている正規表現に一致すると、メールアドレスへのリンクになるよ

<foo@bar.example.com>

19. 改行

• 行の最後に半角スペース2つ、または\(バックスラッシュ)があると(<br />)が入る
• 普通に改行すると別段落になるよ

foo\
bar

baz

何故わざわざ仕様を書いたのか

• 毎度英語とにらめっこするのが面倒
• CommonMarkでググってもヒットするのがMarkdownの問題点を挙げたものばっかり
• それどころかQiitaにはCommonMarkのタグすら存在しなかった

あとがき

• もっとタイプ数を減らす工夫が欲しい（#####が#5と書けるとか）
• 今後はMarkdownでなくCommonMark対応のエディタが普及していってほしい
• でもreSTだとやれることが増えるみたいなのでreST対応のエディタもほしい

おまけ

QiitaのMarkdownの解釈おかしくない？コードブロック内でも解釈しやがるんですけど
GFMの仕様とかじゃなくてQiita側の不具合なんですかね…