サポンテ 勉強ノート

サポンテの勉強ノート・読書メモなどを晒します。

Sphinx の commonmark でリンクやアンカーを設置する

2021/11/26 追記

 この記事では Sphinx で使える commonmark について記載していますが、最近、MyST というものができたようです。以下のリンクをご確認ください。

Sphinx で使える Markdown 方言 'MyST' - Qiita

 すでに common mark で作られている Sphinx 書類をメンテナンスしている方は、引き続き記事をお楽しみください。

はじめに

私は reStructuredText(以下 rst)を使ってて commonmark を使っていないので関係ないのですが、選択肢は多いほうが良い。

commonmark を使っているような方なら、ひょっとしたらすでに知っている情報かもしれませんが、知らなかったり、あるいは commonmark からいずれ rst へ移行したいと考えている方がいるかもしれないため、記法別の対比とともにここに記しておきます。

rst では

rst では以下のような感じでリンクを設置できます。

:doc:`about`
:ref:`label-sample_anchor`
about
===========

.. _label-sample_anchor:

sample section
----------------

Sample text. Sample text. Sample text. Sample text. Sample text. 
Sample text. Sample text. Sample text. Sample text. Sample text. 
Sample text. Sample text. Sample text. Sample text. Sample text. 
Sample text. Sample text. Sample text. Sample text. 

commonmark では

同じように commonmark でリンクを設置する場合は HTML 変換後の拡張子(.html)を含めて指定しなければいけません。

以下のようにします。

[about](about.html)
[sample section](about.html#sample_anchor)

アンカーは、インライン HTML を記述して実現します。

# about

<a id="sample_section"></a>
## sample section

Sample text. Sample text. Sample text. Sample text. Sample text. 
Sample text. Sample text. Sample text. Sample text. Sample text. 
Sample text. Sample text. Sample text. Sample text. Sample text. 
Sample text. Sample text. Sample text. Sample text. 

Sample text. Sample text. Sample text. Sample text. Sample text.
Sample text. Sample text. Sample text. 

つまるところ普通に Markdown の手法を使います。Sphinx ならではのような記法は無いようです。もしそのような記法があれば、それは commonmark ではなく、「MarkdownSphinx 方言」ということになってしまうため、将来にも、そのような記法が現れることはないでしょう。

AutoStructifyコンポーネント を使えば Sphinx 上の Markdown が拡張され「Sphinx 方言」が実現します。

[拡張子を .md で指定できます](about.md)
[これはできません](about.md#sample_anchor)
[これはできる](about.html#sample_anchor)

拡張子(.md)を結局指定する必要があること。内部リンクが使えなくなること。結局は方言になってしまうこと。以上の理由からこのコンポーネントを使うことの優位性はとくにないかなと思います(この点についてのみです。このコンポーネントには他の機能もあります)。

私が Sphinx で commonmark を使わない理由

ひとことで言うなら「rst、別にそれほど難しくない」です。

commonmark でも、上記コンポーネントを使えば「インラインの rst」が使えるようになり、結果、表を実現できます。ですがそんなつぎはぎ記法をするくらいなら全部 rst でいいじゃないかと、正直なところ思いました。

私もはじめは確かに Markdown を捨てる(他でいくらでも使うので捨ててませんが)ことに及び腰でしたが、rst の習得にそれほどの苦はなく、足を踏み出せなかった自分に失笑しました。

皆様も Markdown をある程度覚えたら rst もどうぞ。Sphinx を使っていくなら、いずれ役に立つでしょう。