mdformatでYAML Frontmatterが変換される現象と回避方法について

はじめに

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

要約

• Frontmatterを追加したMarkdownファイルでMarkdownフォーマット向けのライブラリであるmdformatを使用するとFrontmatter部分が変換されてしまう。
• mdformatのプラグインであるmdformat-frontmatterをインストールしてpre-commit hookを設定すれば変換されないようになる。

問題の現象について

mkdocsでmetaタグを生成するのに、Frontmatterを設定しました。¹
しかし、以下のようにFrontmatter部分が変換されてしまう現象が発生しました。

変換前

---
description: Inkscape tips
image: application/inkscape/images/inkscape.png
---

# Inkscape tips

変換後(意図しない変換)

______________________________________________________________________

## description: Inkscape tips image: application/inkscape/images/inkscape.png

# Inkscape tips

解決方法

poetryまたは、pipでmdformat-frontmatterをインストールし、.pre-commit-config.yamlに設定します。^{2 3}

これでpre-commitでmdformat実行時に変換されなくなります。⁴

.pre-commit-config.yaml

  - repo: https://github.com/executablebooks/mdformat
    rev: 0.7.16
    hooks:
      - id: mdformat
        additional_dependencies:
          - mdformat-admon
          - mdformat-footnote
          - mdformat-frontmatter # 追加

その他補足

他のフォーマッタとの比較として、多くの方はVSCodeの拡張機能を使用されていると思いますが、markdownlintではMD25で変換対象にはならないようにルール化されており変換はされません。Prettierでも#4773でサポートされています。

まとめ

mdformatでYAML Frontmatterで作成されたmarkdownファイルが変換される現象と回避方法を紹介しました。

mdformatは他のフォーマッタと比較して本件やmkdocs(Admonitions)のような現象があるのですが、プラグインは開発されており、pre-commitでフォーマットまで実行できるので、pythonでpre-commitを使用されている方にはmdformatを利用するのはありだとおもいます。⁵

本記事がどなたかの参考になれば幸いです。

以上です。

1. Frontmatterの詳細はJekyllの記事を参照ください。
   https://jekyllrb-ja.github.io/docs/step-by-step/03-front-matter/ ↩

2. mdformat-frontmatterはmdformatプラグインですが、プラグインはpre-commit hookで使用する前提のため.pre-commit-config.yamlに追加します。 ↩

3. pre-commitでの使用方法
   https://mdformat.readthedocs.io/en/stable/users/installation_and_usage.html#usage-as-a-pre-commit-hook ↩

4. poetry run mdformat [ファイル名]では変換されるので注意してください。pre-commitのみサポートしています。 ↩

5. 弊環境ではVScodeの機能拡張でmarkdownlitも利用しており、pre-commitではmarkdownlintフックも開発されています。個人的には環境は統一したほうがいいかと思っています。今のところフォーマットの競合などの問題はないですが、markdownlintフックと比較し、導入検討はしたいと思っています。(2023-09-23: markdownlintフックの調査記事をブログに投稿しました。) ↩