Sphinx で使える Markdown 方言 'MyST'

## はじめに

　最近 Sphinx から離れてしまって、この記事の内容もまだ検証できていませんが紹介だけ。

　Sphinx で使える Markdown といえば [CommonMark](https://qiita.com/pashango2/items/d1b379b699af85b529ce)（[recommonmark](https://recommonmark.readthedocs.io/en/latest/index.html)）がすでにありますが、最近 [MyST](https://myst-parser.readthedocs.io/en/latest/) という別の Markdown <ruby><rb>方言</rb><rp>（</rp><rt>Flavored</rt><rp>）</rp></ruby>に対応したようです。

　これで reStructuredText でできることが大体 Markdown でもできるようになったでしょうか。

　Sphinx 固有のなじみの少ない書き方もありますが、それらは追々覚えていくとして、これでまたさらに Sphinx への抵抗感が少なくなりました。

## reStructuredText との比較

　recoomonmark に無くて一番困るのは、[クロスリファレンス](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html?highlight=%3Aref%3A#targets-and-cross-referencing)の `:doc:` や `:ref:` ではないでしょうか。単体ファイルではなく、Sphinx ならではの機能なのに、こればっかりはインライン reStructuredText でやろうとすると冗長になりすぎていました。あとはまあ別に、インライン reStructuredText でも割り切れるのですが。

### :ref: 自由な場所へのクロスリファレンス

```rst:reStructuredText
.. _my-reference-label:

Section to cross-reference
--------------------------

This is the text of the section.

It refers to the section itself, see :ref:`my-reference-label`.
```

```md:MyST
(my-reference-label)=

# Section to cross-reference

This is the text of the section.

It refers to the section itself, see {ref}`my-reference-label`.
```

### :doc: ドキュメントへのクロスリファレンス

```rst:reStructuredText
* See :doc:`this lecture <heavy_tails>` for a definition.
```

```md:MyST
- See {doc}`this lecture <heavy_tails>` for a definition.
```

## Markdown との比較

　Markdown と言っても広いですが...。

### コードフェンス

　[コードフェンス](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html?highlight=%3Aref%3A#parameterizing-directives)は、CommonMark の馴染みのある記法のほかに、行番号を表示したり、特定の行を強調表示したり、面白い書き方ができるようですね。

Markdown

    ```python 
    print('this is python')
    ``` 

MyST

    ```{code-block} python
    print('this is python')
    ```

MyST

    ```{code-block} python
    ---
    lineno-start: 10
    emphasize-lines: 1, 3
    caption: |
        This is my
        multi-line caption. It is *pretty nifty* ;-)
    ---
    a = 2
    print('my 1st line')
    print(f'my {a}nd line')
    ```

## インライン reStructuredText

　reStructuredText の書き方の方が柔軟に対応できると考える場合は、reStructuredText を埋め込むこともできます。

    ```{eval-rst}
    .. figure:: img/fun-fish.png
      :width: 100px
      :name: rst-fun-fish
    
      Party time!
    
    A reference from inside: :ref:`rst-fun-fish`
    
    A reference from outside: :ref:`syntax/directives/parsing`
    ```

## 参考

### MyST について

- [MyST - Markedly Structured Text](https://myst-parser.readthedocs.io/en/latest/)
- [Markdown — Sphinx documentation](https://www.sphinx-doc.org/ja/master/usage/markdown.html)

### MyST のシンタックスハイライトが可能なエディタ

- [MyST-Markdown - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=ExecutableBookProject.myst-highlight)

### その他の参考
- [GitHub Flavored Markdown Spec](https://github.github.com/gfm/)
- [Qiitaで使えるMarkdownまとめ - Qiita](https://qiita.com/sktw/items/9a6daf2cd16df5a810df)
- [QiitaとMarkdownとコンテンツオーサリング - Qiita](https://qiita.com/mizchi/items/17bc6c123207be7e6636#%E3%81%AA%E3%81%9C-markdown-%E3%81%8C%E3%82%A8%E3%83%B3%E3%82%B8%E3%83%8B%E3%82%A2%E3%81%AB%E5%A5%BD%E3%81%BE%E3%82%8C%E3%82%8B%E3%81%8B)