markdownlint

Markdownlint

Markdown ファイルがフォーマット標準に準拠しているか検証します。一貫性のあるドキュメント、読みやすい差分、POSIX 準拠を実現します。

このスキルでできること

1. markdownlint-cli がインストールされているか確認し、未インストールの場合はインストールします。
2. プロジェクト固有の markdownlint 設定を検出し、見つからない場合は最小限のデフォルト設定を使用します。
3. Markdown ファイルのフォーマット、構造、スタイルを検証します。
4. --fix フラグを使って一般的な問題を自動修正できます。エラーがある場合は、該当するルールと修正方法を報告します。

インストールの確認

# Check if markdownlint is available
markdownlint --version 2>/dev/null

インストールされていない場合は、グローバルにインストールします。

npm install -g markdownlint-cli

インストールに失敗した場合（権限の問題、npm がない場合など）は、検証を中止し、解決手順とともに問題を報告します。

• sudo npm install -g ... を使うか、npm の権限を修正します
• Node のバージョン管理ツール（nvm、volta、fnm）を使います
• Node.js がインストールされていない場合はインストールします

検証を黙ってスキップしてはいけません。

設定の検出優先順位

1. プロジェクトルートの .markdownlint.json
2. プロジェクトルートの .markdownlint.yaml
3. プロジェクトルートの .markdownlintrc
4. package.json の markdownlint フィールド
5. デフォルト設定（references/markdownlint-config.json を参照）

プロジェクト設定が見つからない場合は、検証を実行する前に、参照ファイルのデフォルト設定を使って一時的な .markdownlint.json を作成します。

検証ワークフロー

1. Check markdownlint installation
   ├─ Installed → continue
   └─ Missing → install, then continue (fail if install fails)

2. Detect project config
   ├─ Found → use it
   └─ Not found → use default config from references/

3. Run validation
   ├─ Check only:
   │    markdownlint <files-or-directories>
   └─ Auto-fix:
        markdownlint --fix <files-or-directories>

4. Report results
   ├─ Valid → confirm and proceed
   └─ Invalid → show errors, suggest fixes, re-validate after correction

検証方法

ファイルをチェックする（デフォルト）

markdownlint README.md CHANGELOG.md docs/

一般的な問題を自動修正する

markdownlint --fix README.md CHANGELOG.md docs/

注：MD001 heading-increment のように、自動修正できない問題もあり、手動で修正する必要があります。修正後、--fix なしで再実行し、すべての問題が解消されていることを確認してください。

エラー処理

インストールに失敗した場合

markdownlint をインストールできない場合は、エラーを報告し、解決手順を提示します。検証を続行してはいけません。

検証に失敗した場合

検証に失敗した場合は、各エラーについて次の内容を報告します。

• 失敗したルール（例：MD022/blanks-around-headings）
• 問題の内容（例：見出しの前後に空行がない）
• 具体的な修正方法

例：

Validation failed:

1. MD022/blanks-around-headings: heading not surrounded by blank lines
   File: README.md:15
   Fix: add blank lines before and after the heading

2. MD047/single-trailing-newline: file does not end with newline
   File: CHANGELOG.md:89
   Fix: add a single newline at end of file

エラーを報告した後、自動修正可能な問題には markdownlint --fix の実行を提案し、それ以外の問題には手動での修正方法を提示します。修正後、再検証してください。

フォーマットのリファレンス

すべてのルール、一般的な修正方法、自動修正可能なルールについては、references/markdownlint-rules.md を参照してください。