経緯

以前、以下の記事でmkdocsで作成したドキュメントページをpre-commitでmdformatを使用した際にmkdocs(Admonitions)が意図した表示にならない問題と解決方法について投稿しました。

7rikazhexde-techlog.hatenablog.com

今回はtwitter cardに対応するためにコジオン・チェスさんの記事を参考に、descriptionとimageのメタ情報を <meta> タグとして出力されるように設定したのですが、mdformatでfrontmatter部分が変換されてしまい、<meta> タグとして機能しない現象になりました。

kojion.github.io

<meta>タグをHTMLに反映するためにはmetaプラグインとYAML Frontmatterで作成されたmarkdownファイルが必要¹なのですが、
調べるとYAML Frontmatter用のプラグインを使用することで回避することができました。

本記事ではmdformatでYAML 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に設定します。²,³

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

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

pypi.org

まとめ

twitter card用にYAML Frontmatterで作成されたmarkdownファイルが変換される現象と回避方法を紹介しました。これは、はてなブログ等のブログで表示する際に必要なOGPを設定するケースでも同様であり、他のSSGプロジェクトでも同様の現象は起きると思います。

madformatを使用する際は合わせてmdformat-frontmatterをインストールすることをお勧めします。

以上です。

metaプラグインとYAML Frontmatterでメタ情報をmarkdownファイルに記入することで、nav毎に作成されるhtmlに反映されるようになります。YAML Frontmatterについては下記を参照してください。squidfunk.github.iojekyllrb-ja.github.io↩
mdformat-frontmatterはmdformatプラグインですが、プラグインはpre-commit hookで使用する前提のため.pre-commit-config.yamlに追加します。↩
pre-commitでの使用方法https://mdformat.readthedocs.io/en/stable/users/installation_and_usage.html#usage-as-a-pre-commit-hook ↩
poetry run mdformat [ファイル名]では変換されるので注意してください。pre-commitのみサポートしています。↩