---
name: markdown-docs-validator
description: "Audits a Markdown file like a linter and reports every syntax error, dead internal link, heading-order fault, missing alt text, over-long line, and empty code block with its line number. Use when a finished Markdown file needs a lint-style report of syntax errors, dead anchors, heading order faults, missing alt text, and long lines before merging. Do not use for a structural inventory of the document as data, or fixing the problems in place. Related topics: coding, markdown."
---

# Markdown Docs Validator

Audits a Markdown file like a linter and reports every syntax error, dead internal link, heading-order fault, missing alt text, over-long line, and empty code block with its line number.

## When to use

Use this skill when a finished Markdown file needs a lint-style report of syntax errors, dead anchors, heading order faults, missing alt text, and long lines before merging. Do not use it for a structural inventory of the document as data, or fixing the problems in place.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Scan every line for syntax faults: unclosed fences or emphasis, malformed links, inconsistent list markers, ragged tables, each with its line number.
3. Resolve internal anchors against the real headings and flag only malformed external URLs, labeling the rest unverified.
4. Apply the heading rule as Strict or Loose and record skipped levels or duplicate H1s at the matching severity.
5. Check images for allowed extensions and alt text, lines against the length limit outside code and tables, and fences for emptiness.
6. Group findings as Errors, Warnings, and Recommendations and return the report in the chosen format as one block.

## Inputs

- **Markdown source** (longer free text)
- **Check broken links** (choose one: Yes, No)
- **Enforce heading hierarchy** (choose one: Strict, Loose)
- **Allowed image formats** (choose any: png, jpg, svg, gif)
- **Maximum line length** (number from 40 to 120)
- **Report format** (choose one: Plain text, JSON, HTML)

## Output

One block in the chosen format (plain text, JSON, or HTML) with three groups, Errors, Warnings, and Recommendations, where every finding has a line number, the problem, and the suggested fix.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Markdown Docs Validator

Audit my Markdown document and report what is wrong with it.

- Markdown source: {{Markdown source}}
- Check broken links: {{Check broken links}}
- Enforce heading hierarchy: {{Enforce heading hierarchy}}
- Allowed image formats: {{Allowed image formats}}
- Maximum line length: {{Maximum line length}}
- Report format: {{Report format}}

Go line by line and record findings with line numbers; never summarize a class of problem without listing its instances. Check syntax first: unclosed fences, unclosed emphasis, malformed link and image syntax, list markers that switch mid-list, tables whose rows have different column counts. When link checking is on, resolve every internal anchor against the actual headings and every relative path against files the document mentions, and flag external URLs only when they are malformed, since nothing here fetches them. Under Strict, any skipped heading level or a second H1 is an error; under Loose, it is a warning. Flag every image whose extension is outside the allowed formats, every image without alt text, every line over the maximum length outside code blocks and tables, and every empty fenced block. Classify each finding as an Error (renders wrong or links nowhere), a Warning (renders but hurts readers), or a Recommendation (optional improvement). Return the report in the chosen format as a single block with the three groups under clear headings, each finding carrying its line number, the problem, and the fix.

## Pitfalls

- Counting lines inside fenced code blocks against the line length limit, which floods the report with false positives.
- Reporting an external link as broken without having fetched it; only malformed URLs can be judged from the source.
- Treating a skipped heading level as an error under Loose, which makes the strictness toggle meaningless.
