Markdown

Markdown ist eine leichtgewichtige Auszeichnungssprache mit einer simplen Syntax für die Formatierung von Nur-Text. Es gibt sie in vielen syntaktisch unterschiedlichen Varianten. Um Markdown-basierte Dokumentationen zu unterstützen, kann Sphinx MyST-Parser verwenden. MyST-Parser ist eine Docutils-Brücke zu markdown-it-py, einem Python-Paket zum Parsen der CommonMark Markdown-Variante.

Konfiguration

Um Ihr Sphinx-Projekt für Markdown-Unterstützung zu konfigurieren, gehen Sie wie folgt vor

  1. Installieren Sie den Markdown-Parser MyST-Parser

    pip install --upgrade myst-parser

  2. Fügen Sie myst_parser zur Liste der konfigurierten Erweiterungen hinzu

    extensions = ['myst_parser']

    Hinweis

    MyST-Parser erfordert Sphinx 2.1 oder neuer.

  3. Wenn Sie Markdown-Dateien mit anderen Erweiterungen als .md verwenden möchten, passen Sie die Variable source_suffix an. Das folgende Beispiel konfiguriert Sphinx so, dass alle Dateien mit den Erweiterungen .md und .txt als Markdown geparst werden.

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

  4. Sie können MyST-Parser weiter konfigurieren, um benutzerdefinierte Syntax zuzulassen, die Standard-CommonMark nicht unterstützt. Lesen Sie mehr in der MyST-Parser-Dokumentation.