---
name: markdown-docs-analyzer
description: "Maps a Markdown file into structured JSON: the heading tree, every external link, the languages used in code blocks, and the URLs that look broken, so you can audit or script against the document. Use when a Markdown file needs a structural inventory as JSON: heading tree, link list, code block languages, and suspect URLs. Do not use for a pass or fail lint report, or rewriting the document itself. Related topics: coding, markdown."
---

# Markdown Docs Analyzer

Maps a Markdown file into structured JSON: the heading tree, every external link, the languages used in code blocks, and the URLs that look broken, so you can audit or script against the document.

## When to use

Use this skill when a Markdown file needs a structural inventory as JSON: heading tree, link list, code block languages, and suspect URLs. Do not use it for a pass or fail lint report, or rewriting the document itself.

## 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. Parse every heading with its level and line number and build the tree, noting skipped levels.
3. Collect inline, reference, and bare URLs with their type (internal or external) and the line they sit on.
4. Mark links as broken when an anchor has no matching heading or a URL is malformed, and label unfetched external links as unverified.
5. Count fenced code blocks per language tag, folding unselected languages into Other and untagged fences into their own count.
6. Emit one JSON object with the keys headings, links, broken_links, code_blocks, and summary, sized to the chosen output depth.

## Inputs

- **Document** (longer free text)
- **Include heading hierarchy** (choose one: Yes, No)
- **List external links** (choose one: Yes, No)
- **Flag broken links** (choose one: Yes, No)
- **Code block languages to count** (choose any: JavaScript, Python, HTML, CSS, Other)
- **Output depth** (choose one: Summary, Detailed, Full)

## Output

A single JSON object with keys headings (array), links (array), broken_links (array), code_blocks (object of language to count), and summary (string), with detail scaled to the selected depth.

## Prompt template

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

### Markdown Docs Analyzer

Analyze this Markdown document and return its structure as data.

- Document: {{Document}}
- Include heading hierarchy: {{Include heading hierarchy}}
- List external links: {{List external links}}
- Flag broken links: {{Flag broken links}}
- Code block languages to count: {{Code block languages to count}}
- Output depth: {{Output depth}}

Parse the document rather than skimming it. Build the heading tree from ATX and setext headings with their level and line number, and note where a level is skipped. Collect every link and image URL, keep inline, reference-style, and bare URLs, and mark each as internal (anchor or relative path) or external. Treat a link as likely broken when its anchor matches no heading, its relative path is not referenced anywhere else in the document, or the URL is malformed; you cannot fetch URLs, so say "unverified" for external links that merely look fine. Count fenced code blocks by language tag, group the tags outside the selected languages under Other, and count untagged fences separately. Scale the detail to the chosen depth: Summary gives counts only, Detailed adds the items, Full adds line numbers and the text around each finding. Return a single JSON object with the keys headings, links, broken_links, code_blocks, and summary, where summary is a short plain-language paragraph.

## Pitfalls

- Claiming an external URL is live when nothing fetched it; only anchors and malformed URLs can be judged from the text.
- Reading a # inside a fenced code block as a heading, which corrupts the tree.
- Dropping reference-style links because only the inline syntax was searched for.
