docmap

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.