Python str で Markdown を記述する¶

Python の文字列へ書いた Markdown のインデントがずれる場合に、inspect.cleandocで整える方法を紹介する。FastAPI のドキュメントなど、Python のコードの字下げに合わせると Markdown が意図した形で表示されない場面を扱う。

インデントがずれる例¶

次のように Python の文字列で Markdown を記述すると、Markdown のインデントがずれてうまく表示されない。

1
2
3
4

md = """hi
      - list1
      - list2
      """

インデントのずれを解決する方法は、いくつかある。

愚直にインデントを合わせる¶

まず、Markdown のインデントを愚直に合わせる方法がある。

1
2
3
4

md = """hi
- list1
- list2
"""

しかし、この書き方は可読性が悪い。

cleandoc でインデントを削除する¶

次に、Python の文字列のインデントを削除する方法がある。

1
2
3
4
5
6
7
8

from inspect import cleandoc

md = cleandoc(
        """hi
        - list1
        - list2
        """
      )

cleandoc を使うと、Python のインデントを合わせたまま、Markdown のインデントを削除できる。関連するものとして、typing_extensionsにはドキュメント文字列を型アノテーションに付けるDocもある。