Markdown

Markdown は、単純なプレーンテキストフォーマット構文を持つ軽量のマークアップ言語です。それは多くの構文的に異なる フレーバー が存在します。Markdownベースのドキュメントをサポートするために、Sphinxは recommonmark を使用することができます。 recommonmark は CommonMark Markdown フレーバーを解析するためのPythonパッケージである CommonMark-py へのDocutilsブリッジです。

設定

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

  1. Markdownパーサー recommonmark をインストールします:

    pip install --upgrade recommonmark
    

    注釈

    ここで説明する設定には、recommonmarkバージョン 0.5.0 以降が必要です。

  2. recommonmark設定された拡張子<extensions>のリスト に追加します:

    extensions = ['recommonmark']
    

    バージョン 1.8 で変更: バージョン1.8は非推奨で、バージョン3.0は古い recommonmark バージョンで使用されていた source_parsers 設定変数を削除しています。

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

    source_suffix = {
        '.rst': 'restructuredtext',
        '.txt': 'markdown',
        '.md': 'markdown',
    }
    
  4. さらに、標準の CommonMark がサポートしていないカスタム構文を使用できるように recommonmark を構成できます。詳しくは recommonmark documentation をご覧ください。