はじめに
最近 Sphinx から離れてしまって、この記事の内容もまだ検証できていませんが紹介だけ。
Sphinx で使える Markdown といえば CommonMark（recommonmark）がすでにありますが、最近 MyST という別の Markdown 方言に対応したようです。
これで reStructuredText でできることが大体 Markdown でもできるようになったでしょうか。
Sphinx 固有のなじみの少ない書き方もありますが、それらは追々覚えていくとして、これでまたさらに Sphinx への抵抗感が少なくなりました。
reStructuredText との比較
recoomonmark に無くて一番困るのは、クロスリファレンスの :doc: や :ref: ではないでしょうか。単体ファイルではなく、Sphinx ならではの機能なのに、こればっかりはインライン reStructuredText でやろうとすると冗長になりすぎていました。あとはまあ別に、インライン reStructuredText でも割り切れるのですが。
:ref: 自由な場所へのクロスリファレンス
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`.
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: ドキュメントへのクロスリファレンス
reStructuredText
* See :doc:`this lecture <heavy_tails>` for a definition.
MyST
- See {doc}`this lecture <heavy_tails>` for a definition.
Markdown との比較
Markdown と言っても広いですが...。
コードフェンス
コードフェンスは、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`
```