Markdown ドキュメントの一括チェック（リンク切れ・見出し・代替テキスト）

Markdown docs linter for links, headings, alt text and code fences

フォルダ内の Markdown 文書をまとめて調べ、相対リンクや画像のリンク切れ、存在しないアンカー、見出しレベルの飛び、重複見出し、代替テキストの欠落、言語指定のないコードブロック、長すぎる行をレポートにします。

Claude Hermes Agent Codex CursorMIT（改変・再配布・商用利用可）Python

できること

ドキュメントのフォルダを読み取り専用で調べ、Markdown 形式またはJSON 形式のレポートを作ります。

相対リンク・画像（Markdown と <img>・<a href>）のリンク切れ
#見出し へのアンカーが存在しない（GitHub と同じ方式で見出しから生成。日本語の見出しにも対応）
定義のない参照リンク [text][label]、閉じられていないコードブロック
見出しレベルの飛び（## の次に #### など）、同じファイル内の重複見出し、H1 が複数
代替テキストのない画像、言語指定のないコードブロック
長すぎる行（全角文字は幅2で計算。表・URL だけの行・コードは除外）

外部 URL にはアクセスせず、件数だけを表示します。エラーがあると終了コード 1 を返すので、CI のチェックにも使えます。

使い方

python scripts/md_lint.py docs/ README.md --out md-lint.md
python scripts/md_lint.py docs/ --format json --disable long-line --max-line 100

エージェントはレポートをもとに、移動したファイルの正しいパスや実在する見出しを調べて修正案を出し、頼まれたときだけ修正して再チェックします。

必要な環境

Python 3（標準ライブラリのみ）

注意点

静的サイトジェネレーターによっては、ビルド後にだけ有効なリンクの書き方があります。その場合は確認が必要な項目として扱います。
Linux のサーバーではファイル名の大文字・小文字が区別されます。
複雑な HTML の検証はしません。
ファイルの書き換えやネットワーク通信は行いません。

English description

Lint a folder of Markdown docs for broken relative links, images and anchors, heading level jumps, duplicate headings, missing alt text, code fences without a language and very long lines.

What it does

Scans a documentation folder read-only and writes a report in Markdown or JSON.

Broken relative links and images (Markdown, <img> and <a href>)
Anchors that do not exist (GitHub-style heading slugs, including non-Latin headings)
Reference links [text][label] without a definition, and unclosed code fences
Heading level jumps (for example ## followed by ####), duplicate headings in a file, more than one H1
Images without alt text, code fences without a language
Very long lines (wide East Asian characters count as 2; tables, URL-only lines and code are skipped)

External URLs are never fetched, only counted. The exit code is 1 when errors exist, so it also works as a CI check.

How to use

python scripts/md_lint.py docs/ README.md --out md-lint.md
python scripts/md_lint.py docs/ --format json --disable long-line --max-line 100

The agent uses the report to find the correct path of moved files and the real target headings, proposes fixes, applies them only when asked and re-runs the check.

Requirements

Python 3 (standard library only)

Caveats

Some static site generators accept link styles that only work after build; treat those as needing confirmation.
File names are case-sensitive on Linux servers.
Complex HTML is not validated.
No file edits and no network access.

インストール方法

ダウンロードしたZIPを展開します（中に markdown-docs-linter/ フォルダと SKILL.md があります）。
フォルダごと、使うエージェントのスキル置き場にコピーします。
- Claude：~/.claude/skills/（プロジェクト単位なら .claude/skills/）
- Hermes Agent：~/.hermes/skills/
- Codex：~/.agents/skills/／Cursor：~/.cursor/skills/
- Claude アプリ（claude.ai）：「カスタマイズ → スキル」からZIPをアップロード
エージェントを再起動し、スキル一覧に表示されることを確認します。

Windows・Mac 別、エージェント別のインストール手順