Mdformat tips¶

Mdformat は、Markdown ファイルに一貫したスタイルを適用するために使用できる、独自の Markdown フォーマッタです。
コードはpythonで作成されています。

公式ドキュメント¶

https://mdformat.readthedocs.io/en/stable/index.html

インストール¶

公式ドキュメント: Installingを確認してください。pip,poetry,pre-commitでインストールすることはできました。

使い方¶

公式ドキュメント: Command line usageを確認してください。

Info

後述するプラグインを使用する場合、コマンド単体では実行方法がわかりませんでした。
プラグインを使用する場合はpre-commit hookであれば実行できました。
Contributingからプラグインはpre-commit前提で作成する必要があるようです。

pre-commit hookでの指定¶

引数に--checkをつけるとフォーマットまで実行されずにチェックまで実行されます。フォーマットする場合は--checkの指定を無効にします。

  - repo: https://github.com/executablebooks/mdformat
    rev: 0.7.17
    hooks:
      - id: mdformat
        args: ["--check"]
        additional_dependencies:
          - mdformat-admon
          - mdformat-footnote
          - mdformat-frontmatter

プラグイン¶

公式ドキュメント: Pluginsを参照してください。

使用したプラグイン¶

mdformat-admon¶

MkDocsのadmonitionsのためのmdformatプラグインです。

経緯として、mdformatを使用していたところ、以下のように変換されることがわかりました。

変換前¶

!!! info
    - test1
    - test2

変換後¶

!!! info
\- test1
\- test2

mkdocs serveを実行すると、admonitionsの表示は下記のようになります。

これは意図した表示ではありませんでした。この現状を解消するためにmdformat-admonを使用しました。

公式ドキュメントに従いフックを設定します。

  - repo: https://github.com/executablebooks/mdformat
    rev: 0.7.17
    hooks:
      - id: mdformat
        additional_dependencies:
          - mdformat-admon

結果、mdformatによる変換は行われずに意図した表示を確認できました。

Info

2023/08/12時点では以下の通りサポート対象はmkdocsのみとのことです。
将来的にはGitHubのadmonitionsにも対応予定とのことです。

This plugin currently only supports admonitions that start with !!! ... and won't modify admonitions for Github, which should cover most use cases. Future work is planned for other types.