mdformat + mkdocs(Admonitions)で意図した表示にならない現象と解決方法について

はじめに

本記事は以下ブログ記事の転記です。

要約

• mkdocs(Admonitions)で作成した内容にmdformatを実行するとインデントがずれる(修正される)
• mdformatのプラグインであるmdformat-admonを使用すれば修正されない
• mdformat-admonはpre-commitによる使用のみ有効

mkdocs(Admonitions)とは

admonitionsとは、文書内にメモ、ヒント、警告などが目立つようなスタイルで表示してくれる機能です。

infoの例

!!! info
    - test1
    - test2

作成されたwebページ表示

mdformatとは

Markdown用のフォーマッターです。コードはPythonで作成されています。

発生した現象

以下の通り、mdformatによる変換で意図した表示にならない現象が発生しました。

admonitionsに対するmdformatの実行結果

!!! info
\- test1
\- test2

作成されたwebページ表示

解決方法

MkDocsのadmonitionsのためのmdformatプラグインであるmdformat-admonで解決できます。

注意点

公式ドキュメントのContributingに記載されていますが、プラグインを使用するためにはpre-commitで実行する必要があります。

mdformat単体では実行できないため注意が必要です。
(もしかするとやり方があるかもしれませんが、未確認です。)

プラグインの使用方法

pre-commitについては割愛します。詳細は公式ドキュメントを参照ください。
.pre-commit-config.yamlは以下のように記載します。

repos:
  - repo: https://github.com/executablebooks/mdformat
    rev: 0.7.16
    hooks:
      - id: mdformat
        additional_dependencies:
          - mdformat-admon # ここに追加する

実際に使用した結果のページは下記の通りです。
問題なく表示ができることを確認できました。

まとめ

mdformat + mkdocs(Admonitions)で意図した表示にならない現象と解決方法について紹介しました。

mdformatは公式ドキュメントの通り、フォーマットの変更には慎重のようですが、pre-commitによるプラグインが複数存在するため、mkdocsに限らず、目的に応じてプラグインを使用することは有用だと思います。

Welcome to the mdformat developer docs! We’re excited you’re here and want to contribute. ✨

Please discuss new features in an issue before submitting a PR to make sure that the feature is wanted and will be merged. Note that mdformat is an opinionated tool that attempts to keep formatting style changing configuration to its minimum. New configuration will only be added for a very good reason and use case.

以上です。