【markdownlint】使い方完全ガイド｜VS Code拡張・設定ファイル・CLI＆CI自動チェックまで徹底解説

Markdown（マークダウン）でドキュメントや記事を執筆していると、「見出しの階層構造がバラバラになっている」「行末に不要な半角スペースが混ざっている」「リストのインデント幅が揃っていない」といった記法の乱れや表記揺れに悩まされることがよくあります。

特に複数人のチーム開発やオープンソースのドキュメント作成では、各自の書き方の癖によってMarkdownの品質に差が生じがちです。

そんな問題を一発で解決してくれるのが、Markdown専用の静的解析ツール「markdownlint」です。markdownlintを導入すれば、Markdownの構文ルール違反をリアルタイムで警告し、簡単なミスならファイルの保存時に一瞬で自動修正（Auto Fix）してくれます。

本記事では、markdownlintの概要からVS Codeでの導入手順、設定ファイルによるルールカスタマイズ、コメント制御、CLIやGitHub Actionsでの自動チェックまで、エンジニアやテクニカルライターの方にもわかりやすく徹底解説します！

1. markdownlintとは？導入するメリットと仕組み

markdownlint（マークダウンリント）とは、Markdownファイル（.md）の構文やスタイルガイドラインへの準拠度を静的に解析・検証（Lint）するオープンソースツールです。

JavaScript / TypeScript、Python、Rubyなど様々なプログラミング言語にLinter（ESLint、Flake8、RuboCop等）が存在するように、Markdownにも標準的なフォーマットルールを保つためのLinterとして markdownlint がデファクトスタンダードとして広く採用されています。

Markdown静的解析（Linter）の役割

MarkdownはHTMLよりも手軽に記述できる反面、パーサー（変換エンジン）によって解釈の違いが生じやすい記法です。例えば以下のような曖昧さや記述ミスが発生します。

• 見出し記号（#）の後に半角スペースを入れ忘れている
• # 見出し1 の直後にいきなり ### 見出し3 を配置して階層（H2）が抜けている
• 箇条書きリストのインデントが2スペースと4スペースで混在している
• 行末に意図しない不要な半角スペースやタブが残っている

markdownlintはこれらの問題を事前に検知し、エディタ上で波線（警告）を表示したり、ビルドパイプラインでエラーとして報告してくれます。

チーム開発でmarkdownlintを導入すべき3つのメリット

markdownlintのエコシステム一覧

2. 【最速】VS Codeでmarkdownlintを使う手順と初期設定

Visual Studio Code（VS Code）ユーザーであれば、公式拡張機能をインストールするだけで今日からすぐに構文チェックを利用開始できます。

VS Code拡張機能のインストール

1. VS Codeの左サイドバーにある拡張機能アイコン（または Ctrl+Shift+X / Cmd+Shift+X）をクリックします。
2. 検索バーに markdownlint と入力します。
3. 作者が David Anson の markdownlint（ID: DavidAnson.vscode-markdownlint）を選択し、「インストール」をクリックします。

リアルタイムでのエラー検知と修正サジェスト

Markdownファイル内でルールに違反した箇所があると、以下のように警告が表示されます。

• 黄色の波線表示: エラー箇所の文字の下に波線が引かれます。
• ホバーで詳細説明: 波線部分にマウスカーソルを合わせると、「MD001/heading-increment/header-increment: Heading levels should only increment by one level at a time」のようにルールIDと原因が表示されます。
• クイックフィックス（電球アイコン）: Ctrl+.（Macは Cmd+.）を押すと、ワンクリックで推奨形式に修正できます。
• 問題パネル（Problems）の一覧表示: Ctrl+Shift+M（Macは Cmd+Shift+M）でワークスペース内のすべての警告を一括確認できます。

保存時に自動修正（Auto Fix）する settings.json の設定

markdownlintの真価を発揮させるには、「ファイルを保存した瞬間に自動で整形・修正する設定」を有効にするのがおすすめです。

VS Codeの設定ファイル（settings.json）に以下の記述を追加してください。

{
  // Markdownファイル保存時に自動修正（Auto Fix）を実行
  "[markdown]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "DavidAnson.vscode-markdownlint",
    "editor.codeActionsOnSave": {
      "source.fixAll.markdownlint": "explicit"
    }
  }
}

3. 設定ファイル（.markdownlint.json / yaml）によるルールカスタマイズ

デフォルトのmarkdownlintルールは非常に厳格です。例えば「1行80文字を超えてはならない（MD013）」や「HTMLタグを使ってはならない（MD033）」などは、日本語のWeb記事やドキュメント作成では不都合が生じることが多いです。

プロジェクトに合わせたルール設定ファイルを作成することで、特定のルールを無効化したりパラメータを調整できます。

設定ファイルの配置場所と優先順位

設定ファイルはプロジェクトのルートディレクトリに配置します。markdownlintは以下のファイル名に対応しており、上にあるものが優先して読み込まれます。

1. .markdownlint-cli2.jsonc / .markdownlint-cli2.yaml（cli2専用設定）
2. .markdownlint.jsonc / .markdownlint.json（JSON形式）
3. .markdownlint.yaml / .markdownlint.yml（YAML形式）
4. .markdownlint.cjs / .markdownlint.mjs（JavaScript形式）

.markdownlint.json の基本構造とコピペ用テンプレ

プロジェクトのルートに .markdownlint.json を作成し、以下の設定をコピペして利用するのが最も実用的でおすすめです。

{
  "default": true,

  // MD013: 1行の文字数制限（日本語執筆では改行しないことが多いため無効化）
  "MD013": false,

  // MD033: インラインHTMLの許可（装飾タグやdetailsタグを許可）
  "MD033": {
    "allowed_elements": [
      "div", "span", "p", "br", "hr",
      "details", "summary",
      "kbd", "sub", "sup", "b", "i", "u",
      "table", "thead", "tbody", "tr", "th", "td",
      "img", "a"
    ]
  },

  // MD024: 同名見出しの重複（セクションが異なれば同じ見出し名を許可）
  "MD024": {
    "siblings_only": true
  },

  // MD007: リストのインデント幅（スペース2つに統一）
  "MD007": {
    "indent": 2
  },

  // MD029: 番号付きリストの連番形式（1. 2. 3. 順の連番を強制）
  "MD029": {
    "style": "ordered"
  },

  // MD041: ファイル先頭にH1見出しを強制するルール（Front Matter等を使う場合は無効化）
  "MD041": false
}

.markdownlint.yaml（YAML形式）での書き方

YAML形式が好まれるプロジェクトでは、.markdownlint.yaml として以下のように記述します。

default: true

# 1行の文字数制限を無効化
MD013: false

# インラインHTMLの一部要素を許可
MD033:
  allowed_elements:
    - div
    - span
    - details
    - summary
    - br
    - img

# 同一親見出し配下のみ重複チェック
MD024:
  siblings_only: true

# リストのインデント幅を2スペースに設定
MD007:
  indent: 2

# ファイル先頭のH1強制を無効化
MD041: false

無視するファイル・フォルダの指定（.markdownlintignore）

node_modules や自動生成されたドキュメント、外部ライブラリのMarkdownをチェック対象から除外したい場合は、プロジェクトルートに .markdownlintignore ファイルを作成します。（.gitignore と同じ構文です）

# 依存パッケージとビルド出力
node_modules/
dist/
build/
.site/

# 自動生成ドキュメント
docs/generated/
CHANGELOG.md

4. よく引っかかるmarkdownlintの代表的ルール一覧と対処法

markdownlintには50種類以上の組み込みルールが存在します。ここでは、執筆中に最も頻繁に遭遇する重要ルールとその意味・修正方法を解説します。

主要ルール早見表（ルールID一覧）

MD001: Heading levels should only increment by one level at a time

見出しの階層が1段階ずつ増えていない場合に発生します。SEO的にも文書構造的にもNGとされるパターンです。

# 記事タイトル（H1）
### サブセクション（H3） ← MD001エラー！

# 記事タイトル（H1）
## メインセクション（H2）
### サブセクション（H3）

MD009: Trailing spaces（行末スペース）

行の末尾に不要なスペースが存在すると警告されます。Markdownでは「末尾の半角スペース2個＝強制改行」という仕様がありますが、意図しないゴミスペースが混ざることが多いため、markdownlintは警告を出します。

VS Codeで自動修正を有効にしておけば、ファイルを保存するだけで自動的に末尾スペースが削除されます。

MD013: Line length（1行文字数制限）の無効化・緩和

デフォルトでは1行80文字（全角で約40文字）を超えるとエラーになります。英語の文章では段落ごとに細かく改行する習慣がありますが、日本語の執筆環境では文章が長くなることが自然であるため、"MD013": false で無効化するのが一般的です。

MD024: Multiple headings with the same content（同名見出し）

同一ドキュメント内に同じ見出し名が複数あると警告されます。例えば各章ごとに「まとめ」「使い方」といった同名見出しを付けたい場合は、設定ファイルで "siblings_only": true を指定すると、同じ親見出し（兄弟関係）の直下でなければ同名見出しが許可されます。

MD033: Inline HTML（HTMLタグの直接記述許可）

Markdown内で <div>、<details>、<img>、<br> などのHTMLタグを書くと発生します。リッチな表現のためにHTMLを併用したい場合は、設定ファイルの allowed_elements で使用したいタグ名をホワイトリスト登録するか、"MD033": false で完全に解除します。

MD041: First line in a file should be a top-level heading

ファイルの1行目が # タイトル から始まっていないと警告されます。JekyllやHugo、Docusaurusなどの静的サイトジェネレーターでファイルの先頭にFront Matter（YAMLヘッダー ---）を記述する場合に引っかかりやすいため、そのような環境では無効化（"MD041": false）します。

5. 特定行やブロックでルールを無効化するコメント記法

「全体の設定ファイルではルールを有効にしておきたいが、この特定の箇所だけは例外的にルールを無視したい」という場合、Markdownファイル内に特殊なHTMLコメントを記述することで局所的にLinterの挙動を制御できます。

次の1行だけ無効化（disable-next-line）

コメントの直後にある「次の1行」だけ特定のルールを無効化します。最も安全で利用頻度の高い書き方です。

この行だけHTMLタグの警告を無視



非常に長いURLを含むリンク

ブロック区間のみ無効化（disable 〜 enable）

複数行にわたる特定のセクションのみルールを無効化し、終わったら再度有効化します。

  

    
長いテキストを含む表組みブロック
  

ファイル全体で無効化（disable-file）

ファイルの先頭に記述することで、そのファイル全体で特定ルール（または全ルール）を無効化します。

# このファイル全体でMD033とMD041のチェックをスキップ

コメント制御記法チートシート

6. コマンドライン（CLI）での一括チェック＆自動修正

プロジェクト内のすべてのMarkdownファイルを一括でチェックしたり、コミット前フック（lint-staged / Husky）に組み込む場合はCLIツールを使用します。

markdownlint-cli と markdownlint-cli2 の違い

現在CLIツールには2種類存在しますが、結論から言うと「markdownlint-cli2」の利用を強く推奨します。

• markdownlint-cli: 従来からある標準CLI。直列処理のためファイル数が多いと低速。
• markdownlint-cli2: 後発のモダンCLI。非同期並列処理により圧倒的に高速で、設定ファイルの自動検索やGitignore連携が強化されています。

npx でインストール不要の即時実行

Node.jsがインストールされている環境であれば、npx コマンドを使ってパッケージのインストールなしで即座にチェックを実行できます。

# カレントディレクトリ配下のすべてのMarkdownファイルをチェック
npx markdownlint-cli2 "**/*.md" "#node_modules"

# 特定のフォルダ（docs配下）のみチェック
npx markdownlint-cli2 "docs/**/*.md"

一括自動修正コマンド（–fix）の実行

ルール違反のうち自動修正（Auto Fix）が可能な項目を一発で一括整形するには、--fix 引数を付与して実行します。

# プロジェクト内の全Markdownファイルを一括自動修正
npx markdownlint-cli2 --fix "**/*.md" "#node_modules"

package.json の scripts に登録しておくと、開発メンバー全員が同じコマンドで実行できるため便利です。

{
  "scripts": {
    "lint:md": "markdownlint-cli2 \"**/*.md\" \"#node_modules\"",
    "lint:md:fix": "markdownlint-cli2 --fix \"**/*.md\" \"#node_modules\""
  },
  "devDependencies": {
    "markdownlint-cli2": "^0.17.0"
  }
}

7. GitHub Actions（CI）でMarkdown構文チェックを自動化する手順

GitHub上でチーム開発を行う場合、GitHub Actionsのワークフローを作成しておけば、Pull Request（PR）が作成された際に自動でMarkdownの構文チェックが走り、ルール違反を検知できます。

ワークフローファイル（.github/workflows/markdownlint.yml）の作成

リポジトリの .github/workflows/markdownlint.yml に以下のワークフロー定義を作成します。

name: Markdown Lint

on:
  push:
    branches: [ main, master ]
  pull_request:
    branches: [ main, master ]

jobs:
  markdownlint:
    name: Runner / markdownlint
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Run markdownlint-cli2 action
        uses: DavidAnson/markdownlint-cli2-action@v19
        with:
          globs: |
            **/*.md
            !node_modules/**
            !.site/**

Pull Request時の自動チェックとレビュー効率化

このワークフローを導入すると、以下の効果が得られます。

• CIステータスバッジの表示: PR画面でLinterチェックが成功したか（緑チェック）失敗したか（赤バツ）が一目でわかる
• 違反箇所のインライン注釈: GitHubのファイル変更（Files Changed）画面上に、markdownlintのエラー行が自動でアノテーション表示される
• マージブロック設定: 「Linterがパスしないとマージできない」ブランチ保護ルール（Branch Protection Rule）を設定可能

8. markdownlintが動かない・反映されない時のトラブルシューティング

9. まとめ＆Markdown執筆環境を強化するおすすめ関連記事

markdownlintは、個人でのドキュメント作成から大規模チームでのWeb開発・CIパイプラインまで、Markdownの品質を自動で担保してくれる必須の静的解析ツールです。