Markdown

Markdown は、単純なプレーンテキストフォーマット構文を備えた軽量マークアップ言語です。 それには flavors と呼ばれる構文的に異なるものがたくさん在ります。 Markdown ベースのドキュメンテーションをサポートするために、Sphinx は MyST-Parser を使うことができます。 MyST-Parser は、 CommonMark Markdown flavor を解析するための Python パッケージである markdown-it-py への Docutils ブリッジです。

設定

SphinxプロジェクトをMarkdownサポート用に設定するには、次の手順に従います。

1. Markdown パーサーの MyST-Parser をインストールします

   pip install --upgrade myst-parser
   

2. :confval:`設定された extension <extensions> のリスト ` に myst_parser を追加する。

   extensions = ['myst_parser']
   

   注釈

   MyST-Parser は Sphinx 2.1 以上を必要とします。

3. .md 以外の拡張子を持つMarkdownファイルを使用する場合、 source_suffix 変数を調整してください。次の例では、Sphinxが拡張子 .md と .txt を持つすべてのファイルをMarkdownとして解析するように設定しています:

   source_suffix = {
       '.rst': 'restructuredtext',
       '.txt': 'markdown',
       '.md': 'markdown',
   }
   

4. MyST-Parser をさらに設定すると、標準の CommonMark がサポートしていないカスタム構文の使用を許すことができるようになります。 そのためには MyST-Parser documentation をさらに読んでください。