docmap

name	docmap
description	Navigate markdown, PDF, and YAML documentation structure without reading full files. Use before opening any large .md file, to locate specific constructs (code blocks, callouts, tables), to jump to a line number's context, or to see what changed in docs since a git ref.

docmap skill

docmap is a local CLI that turns a markdown file into a typed AST and surfaces every construct as a jump target. Use it as your first read of any documentation you haven't seen before.

When to invoke

Reach for docmap when any of these is true:

• You're about to Read a markdown file larger than ~200 lines
• You need to find a specific kind of content (code block, callout, table, math block, footnote, task list, wiki link)
• You have a line number (from grep, diff, error, user) and need to know what construct lives there
• You want to see what changed in docs since a git ref
• You're exploring an unfamiliar repository and want a project-wide inventory
• You want structured JSON output of a document's AST

Do not invoke docmap for:

• Short READMEs that fit in context anyway
• Non-documentation markdown (chat logs, commit messages, issue bodies)
• Markdown files you've already read in this session

Command reference

Directory inventory

docmap .
docmap docs/

Returns a project-wide inventory header (total callouts, code blocks, tables, tasks, etc.) plus a one-line digest per file. Use this to decide which file to drill into.

Single-file tree

docmap README.md

Returns a dense tree where each section carries an inline annotation of its notable contents. Every construct has a :line jump target.

Drill into one construct type

docmap file.md --type <kind>

Valid kinds: code, callout, table, math, footnote, deflist, linkref, html, task, wiki, embed, mention, issue, sha, emoji.

Sub-filters:

docmap file.md --type code --lang python
docmap file.md --type callout --kind warning

Output lists every matching construct grouped by containing section, with exact line ranges.

Reverse lookup (line → construct)

docmap file.md --at 154

Returns the section breadcrumb and node type at line 154. Use this when you have a line number from anywhere (grep, diff, error, LSP) and need to know what it actually is.

Changed since git ref

docmap file.md --since HEAD~5
docmap file.md --since main

Shows only the constructs that sit on lines modified since the given git ref. Uses git diff --unified=0 under the hood.

Search across notables

docmap file.md --search "python"
docmap . --search "warning"

Searches section titles and content plus the typed AST: code block languages, callout variants, table headers, math TeX, footnote IDs, link labels, HTML content. Much broader than a plain grep.

Focused section view

docmap file.md --section "Installation"    # Just that subtree
docmap file.md --expand "Installation"      # Raw content of that section

Cross-file references

docmap . --refs

Shows which docs link to which other docs — useful for understanding doc graph topology.

JSON output

docmap file.md --json
docmap . --json | jq '.documents[] | select(.summary.code_blocks > 10)'

Full typed AST including per-section notables, top-level summary counts, and every node with its kind + line range. Pipe into jq or another tool.

Reading the output

The header box shows the file's full inventory:

╭──── file.md ────╮
│ Sections: 30 │ ~2.3k tokens                     │
│ 5 callouts · 4 tables · 8 code blocks · 2 math  │
│ 6 tasks (3 done) · 4 wiki · 6 embeds            │
╰──────────────────────────────────────────────────╯

Every section line in the tree has the shape:

├── <title> (<tokens>) · <annotation>

Where <annotation> packs every notable construct in that section:

• go :142-149, python :154-156, bash :161-162 — code blocks by language and line range
• note :219, tip :222, warning :228 — callouts by variant and line
• 4 tables :108 Name, :116 Left, :123 Field — tables with first-header identification
• ^1 :276, ^bignote :277 — footnote definitions by ID
• 6 tasks (3 done) — aggregate task list counts
• 4 wiki · 6 embeds — Obsidian aggregate counts

The :NNN format is a 1-indexed source line. Same convention as grep, ripgrep, vim, and compiler errors. :154-156 means "lines 154 through 156."

Typical agent workflows

Workflow: skim before read

docmap unfamiliar.md                    # Get the structure
docmap unfamiliar.md --at 247           # What's at the section I care about?
# Now do a targeted Read on just lines 240-280

Workflow: find every instance of a construct

docmap huge-doc.md --type code --lang go        # Every Go snippet
docmap huge-doc.md --type callout --kind warning # Every warning

Workflow: understand changes

git checkout feature-branch
docmap docs/api.md --since main         # What did this PR change?

Workflow: project-wide discovery

docmap .                                # Header shows aggregate totals
# "there are 41 code blocks and 18 callouts in this repo"
# Decide which file is worth opening based on the per-file digest

Workflow: structured consumption

docmap file.md --json | jq '.documents[0].nodes[] | select(.kind == "code_block")'

What docmap recognizes

Full CommonMark + GitHub Flavored Markdown + Obsidian extensions. Block constructs: frontmatter (YAML/TOML/JSON), ATX + Setext headings, paragraphs, blockquotes, GFM callouts (5 kinds), ordered/unordered/task lists, tables with alignment, fenced + indented code blocks, math blocks, footnote definitions, definition lists, HTML blocks, thematic breaks, link reference definitions. Inline constructs: links, autolinks (angle-bracket + GFM bare + email), images, emphasis/strong/strikethrough, inline code, inline math, footnote refs, wiki links ([[…]]), wiki embeds (![[…]]), mentions (@user), issue refs (#123, user/repo#123, GH-123), commit SHAs, emoji shortcodes, HTML entities.

Pair with codemap

codemap .   # code structure (filesystem + symbols)
docmap .    # doc structure (sections + notables)

Together, they give an agent full spatial awareness of a repository without reading any source file first.