SphinxでMarkdown拡張言語のMySTを扱う

はじめに

SphinxでMarkdownの拡張言語であるMyST (Markedly Structured Text) を導入する方法をまとめました。

SphinxはPython製のドキュメント生成ツールです。Sphinxは標準でReST (reStructuredText) と呼ばれるマークアップ言語をサポートしています。SphinxでMarkdownまたはMySTを導入する場合、myst-parserというプラグインを導入します

この記事では、Sphinxとmyst-parserを導入する方法と、MySTによる記事の作成方法を述べます。

Sphinxをはじめよう第3版

posted with ヨメレバ

清水川貴之/小宮健オライリー・ジャパン 2022年03月24日頃

楽天ブックス

Amazon

Kindle

ReSTとMySTについて

ReSTは表現力の高いマークアップ言語であり、標準的なMarkdownではできない以下のような記述が可能です（ただし、一部のMarkdown方言はサポートしているかもしれません）。

任意の場所への目次 (toctree) の生成
脚注 (footnote)
画像の左寄せ・右寄せ
テーブル（表）の結合セル

しかし、Markdownを既に習得しているユーザにとっては、ReSTを勉強するのは手間です。そこで、Sphinxにプラグインを追加し、Markdown方言であるMySTで記事を作成できるようにします。

MySTはCommonMarkを拡張した言語（上位セット）です（CommonMarkはMarkdownの仕様を明確にした言語で、2014年に開発されました。以降では、MarkdownはCommonMarkのことを指します）。MySTでは、ReST形式で表現できることの大半を表現できます。

なお、かつてはrecommonmarkという、SphinixでCommonMarkを利用できるプラグインがありました。しかし、現在は開発が停止されており、使用は推奨されていません。

環境

OSはWindows 10 Home Ver. 21H1です。

ソフトウェア	バージョン
Python	3.8.5
Sphinx	4.4.0
myst-parser	0.17.0

Sphinxとmyst-parserのインストール

Pythonは既にインストールされているものとして、Sphinxとmyst-parserをインストールします。Condaとpipのどちらでもインストール可能ですが、myst-parserではCondaが推奨されています。

Conda環境では以下を実行します。-cオプションによって、インストール元のチャンネルを指定します。

1
2


conda install -c anaconda sphinx
conda install -c conda-forge myst-parser

pipの場合は以下を実行します。

1
2


pip install sphinx
pip install myst-parser

プロジェクトテンプレートの作成

適当な空フォルダを作成し、sphinx-quickstartコマンドを実行してプロジェクトテンプレートを作成します。詳細は以下の記事を参考にしてください。

Sphinxを使ったHTMLドキュメント作成

設定ファイルの編集

Sphinxの設定ファイルconf.pyを開き、extensionsにmyst-parserを追加します。

1

extensions = ["myst_parser"]

これによって、SphinxはReST (.rst) とMarkdown (.md) の両方を扱えるようになります（ファイルの形式は拡張子で判定されます）。

Markdownファイルの作成とビルド

Markdownファイルを追加します。index.rstと同じフォルダにtest.mdというファイルを作成し、中身を以下のように書きます。

1
2
3
4
5
6
7
8
9


# MyST Test

Hello, MyST.

> Blockquote 

1. spam
1. ham
1. eggs

次に、index.rstを開き、以下のようにtest.mdを追加します。ここで、test.mdとtoctreeの先頭位置を揃えるようにインデントが必要です。index.rstはビルド後にindex.htmlに変換されるファイルです。また、toctreeは目次を生成するディレクティブ（指示）です。

1
2
3
4
5


.. toctree::
   :maxdepth: 2
   :caption: Contents:

   test.md

上記のように追記することにより、test.mdがドキュメントに追加されたことをSphinxに教えます。

最後に、以下のコマンドを実行してHTMLファイルをビルドします。

1

.\make.bat html

コマンドの実行後、build/html/test.htmlというファイルが生成されているはずです。これを開くと、MarkdownファイルをHTMLファイルに変換できたことが確認できます。

test.html

まとめ

SphinxでMarkdownの拡張言語であるMyST (Markedly Structured Text) を導入する方法をまとめました。
MyST独自の記法については、以下の記事でまとめています。
SphinxでMarkdown拡張言語のMySTを扱う – Helve Tech Blog