✍
Zenn記事を書くときのmarkdownlint設定：URL自動フォーマットの回避

2025/10/02に公開
 はじめにぐりもお（@gr1m0h）です。
最近、技術ブログをzennで書くことが多くなり、執筆環境の改善に取り組んでいます。その一環として、LazyVimのMarkdown Extraを導入し、Markdownのlintとformatを行うようにしました。
http://www.lazyvim.org/
これにより、記事の品質を保ちながら効率的に執筆できるようになったのですが、zenn特有の記法と相性が悪い部分がありました。
具体的には、記事内にURLをそのまま記述すると、formatにより<>で囲われてしまい、zennのレンダリング結果が意図したものにならないという問題です。
調査したところ、この挙動はmarkdownlintのMD034というルールによるものでした。そのため、MD034を設定で除外することで問題を解決できると考え、実際に試してみました。
本記事では、MD034が何であるか、そしてLazyVimでどのように除外設定を行うかについて説明します。

 MD034とはMD034は、markdownlintのルールの一つで、「Bare URL used」という名前がついています。このルールは、URLがそのまま記述されている場合に警告を出すものです。
https://github.com/DavidAnson/markdownlint/blob/main/doc/md034.md
markdownlintは、Markdownの標準的な記法として、URLを以下のいずれかの形式で記述することを推奨しています。
リンク形式: [表示テキスト](https://example.com)
山括弧で囲む形式: <https://example.com>
これらの形式を使うことで、URLであることが明示的になり、Markdownパーサーが確実にリンクとして認識できるようになります。そのため、MD034ルールが有効になっていると、https://example.comのようなURLは<https://example.com>にフォーマットされます。
しかし、zennではURLをそのまま記述した場合、自動的にリンクとして認識され、適切にレンダリングされます。一方で、<>で囲まれたURLは、zennのMarkdownレンダリングエンジンによって意図しない表示になることがあります。このような背景から、zennの記事を書く場合は、MD034ルールを除外する必要があると考えました。

 LazyVimのMarkdown ExtraLazyVimでは、:LazyExtrasコマンドからlang.markdownを追加することで、Markdownファイルの編集体験を向上させることができます。
https://www.lazyvim.org/extras/lang/markdown
Markdown Extraには、以下のツールとプラグインが含まれており、それぞれが連携してMarkdown編集をサポートします。
markdownlint-cli2: Markdownのlintツール（mason経由でインストール）
marksman: MarkdownのLSP（補完、定義ジャンプなど）
markdown-preview.nvim: ブラウザでのプレビュー
render-markdown.nvim: Neovim内でのリアルタイムレンダリング
markdown-toc: 目次の自動生成
また、conform.nvimやnvim-lintが導入されている場合、markdownlint-cli2が自動的に統合され、保存時やフォーマット時にルール違反を検出・修正します。デフォルトではmarkdownlintの全ルールが有効になっているため、MD034も自動修正の対象となります。

 MD034の除外方法MD034を除外するには、2つのアプローチがあります。それぞれの方法には特徴があるため、markdownlint-cli2の設定ファイル検索の仕組みを理解した上で、適切な方法を選択することが重要です。

 設定ファイルの検索の仕組みまず、markdownlint-cli2がどのように設定ファイルを検索するかを理解しておきましょう。

markdownlint-cli2は、実行されたディレクトリとそのサブディレクトリ内で設定ファイルを検索します。そのため、プロジェクトルートに配置された設定ファイルは自動的に検出されますが、$HOMEに配置された設定ファイルは明示的にパスを指定しないと検出されません。
これは、nvim-lintがmarkdownlint-cli2を実行する際、編集中のファイルのディレクトリをカレントディレクトリとして実行するためです。したがって、$HOME/.markdownlint.jsonのようにホームディレクトリに配置した設定は、検索パスに含まれず、自動的には適用されません。

 1. プロジェクトルートでの設定プロジェクトのルートディレクトリに.markdownlint.jsonファイルを作成し、除外したいルールを指定します。この方法では、パスの指定が不要で設定が自動的に適用されます。
{
  "MD034": false
}
zennの記事を書くプロジェクトディレクトリに配置することで、そのプロジェクト内でのみMD034ルールが無効化されます。
cd ~/path/to/zenn-articles
cat << EOF > .markdownlint.json
{
  "MD034": false
}
EOF
この設定ファイルは、プロジェクト内のすべてのMarkdownファイルに対して自動的に適用されます。また、他のルールも除外したい場合は、以下のように指定できます。
{
  "MD034": false,
  "MD033": false,
  "MD041": false
}

 2. グローバル設定全てのプロジェクトでMD034を除外したい場合は、任意の場所（e.g., ~/.config/nvim/）に設定ファイルを配置できます。ただし、前述の検索の仕組みにより、この設定を有効にするには~/.config/nvim/lua/plugins/lint.luaでパスを明示的に指定する必要があります。
cat << EOF > ~/.config/nvim/.markdownlint.json
{
  "MD034": false
}
EOF
次に、~/.config/nvim/lua/plugins/lint.luaを作成し、markdownlint-cli2の設定を上書きします。
return {
  {
    "mfussenegger/nvim-lint",
    opts = {
      linters_by_ft = {
        markdown = { "markdownlint-cli2" },
      },
      linters = {
        ["markdownlint-cli2"] = {
          args = { "--config", vim.fn.expand("~/.config/nvim/.markdownlint.json"), "--" },
        },
      },
    },
  },
}
この設定により、nvim-lintがmarkdownlint-cli2を実行する際に、--configオプションで設定ファイルのパスを明示的に指定します。
ただし、個人的には、プロジェクトごとに異なるMarkdown記法の要件がある可能性を考慮して、プロジェクト単位で設定することをおすすめします。

 3. 設定の反映設定ファイルを作成したら、Neovimを再起動します。
再起動後、Markdownファイルを開いて、裸のURLを記述しても警告が出ないこと、また自動修正で<>が追加されないことを確認してください。
markdownlint-cli2の詳細な設定方法については、以下のドキュメントを参照してください。
https://github.com/DavidAnson/markdownlint-cli2
また、LazyVimでのMarkdownlintの設定に関するコミュニティディスカッションも参考になります。
https://github.com/LazyVim/LazyVim/discussions/2268
https://www.reddit.com/r/neovim/comments/1hja91t/lazyvim_how_can_i_disable_these_in_my_markdown

 動作確認設定が正しく適用されているかを確認するために、以下の手順を試してみましょう。

まず、テスト用のMarkdownファイルを作成します。
# テスト

以下のURLはそのままの状態です。

https://zenn.dev/
このファイルを保存したときに、<>で囲まれないことを確認します。また、診断メッセージ（:LspInfoや診断ウィンドウ）にMD034の警告が表示されないことを確認します。

もし設定が反映されない場合は、以下の点を確認してください。
.markdownlint.jsonファイルがプロジェクトのルートディレクトリに配置されているか
JSONの構文が正しいか
Neovimを再起動したか、LSPを再起動したか

 さいごにLazyVimでMarkdownのMD034ルールを除外する方法について紹介しました。
zennの記事を書く際には、このような設定が必要になることがあります。markdownlintは便利なツールですが、プラットフォーム固有の記法との相性を考慮して、適切にルールを調整することが重要だと思います。
今後、他のMarkdownルールについても、同様の方法で除外設定を行うことができます。必要に応じて.markdownlint.jsonを更新し、自分の執筆スタイルに合わせた環境を構築していければと考えています。
はじめに

MD034とは

LazyVimのMarkdown Extra

MD034の除外方法

設定ファイルの検索の仕組み

1. プロジェクトルートでの設定

2. グローバル設定

3. 設定の反映

動作確認

さいごに

Discussion
