Markdownを作成していると、VSCodeのmarkdownlint拡張機能からさまざまな警告が表示されることがあります。
markdownlintはMarkdownの品質向上に役立つ便利なツールですが、すべてのルールがすべての用途に適しているわけではありません。
特に技術ブログや手順書、ナレッジベースを作成していると、
- 1行が長くなりやすい
- 同じ見出しを繰り返し使用したい
- URLやコードが長くなる
といったケースが頻繁に発生します。
今回は、VSCodeでmarkdownlintの警告ルールをカスタマイズする方法について紹介します。
markdownlintとは
markdownlintは、Markdownの書き方をチェックしてくれるツールです。
例えば以下のような内容を検出できます。
- 見出しの階層がおかしい
- 空行が不足している
- 行の長さが長すぎる
- 同じ見出しが重複している
ルールに従ってMarkdownを書くことで、可読性や保守性を高めることができます。
一方で、実際の運用では「このルールは不要だな」と感じることも少なくありません。
markdownlintの設定ファイルを作成する
markdownlintのルールは設定ファイルで変更できます。
プロジェクトのルートディレクトリに以下のファイルを作成します。
.markdownlint.jsonファイル構成の例です。
project/
├─ article.md
├─ README.md
└─ .markdownlint.jsonVSCodeでMarkdownファイルを開くと、自動的に設定が反映されます。
ルールを無効化する方法
不要な警告は設定ファイルで無効化できます。
例えば以下のように記述します。
{
"MD013": false,
"MD024": false
}これで対象ルールの警告は表示されなくなります。
ルールを緩和する方法
完全に無効化したくない場合は、条件を緩和することも可能です。
例えば行長制限を200文字に変更する場合は以下のように設定します。
{
"MD013": {
"line_length": 200
}
}これにより極端に長い行だけを検出できるようになります。
実際によく見かける警告
MD013: line-length
MD013/line-length: Line length1行の文字数が長すぎる場合に表示されます。
- 長いURL
- SQL
- APIサンプル
- コードブロック
などを扱う場合は、頻繁に発生します。
MD024: no-duplicate-heading
MD024/no-duplicate-heading:
Multiple headings with the same content同じ見出しが複数存在する場合に表示されます。
例えば次のようなケースです。
## 設定方法
...
## 設定方法
...マニュアルやナレッジ集では意図的に同じ見出しを使うこともあるため、必ずしも修正が必要とは限りません。
私のおすすめ設定
技術ブログや技術メモを中心に執筆している場合は、以下の設定がおすすめです。
{
"MD013": false,
"MD024": false
}特に以下のようなコンテンツを扱う方には相性が良いと思います。
- Python
- SQL
- PowerShell
- Bash
- APIドキュメント
- 手順書
ルールに合わせるために無理やり文章や構成を変更するより、用途に応じてルールを調整した方が執筆しやすい場合もあります。
まとめ
markdownlintはMarkdownの品質を保つための便利なツールですが、実際の利用シーンによっては不要な警告が発生することがあります。
そんなときは、.markdownlint.json を作成してルールを調整することで、自分に合った環境を作ることができます。
まずは必要なルールだけを残し、不要なルールは無効化または緩和しながら快適なMarkdown執筆環境を整えてみてください。
コメント