JavaScriptを有効にしてください

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

 ·   4 min read

はじめに

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

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

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

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を開き、extensionsmyst-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.mdtoctreeの先頭位置を揃えるようにインデントが必要です。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

参考

シェアする

Helve
WRITTEN BY
Helve
関西在住、電機メーカ勤務のエンジニア。Twitterで新着記事を配信中です

サイト内検索