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 ```bash 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 ```bash 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 ```bash docmap file.md --type <kind> ``` Valid kinds: `code`, `callout`, `table`, `math`, `footnote`, `deflist`, `linkref`, `html`, `task`, `wiki`, `embed`, `mention`, `issue`, `sha`, `emoji`. Sub-filters: ```bash 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) ```bash 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 ```bash 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 ```bash 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 ```bash docmap file.md --section "Installation" # Just that subtree docmap file.md --expand "Installation" # Raw content of that section ``` ### Cross-file references ```bash docmap . --refs ``` Shows which docs link to which other docs — useful for understanding doc graph topology. ### JSON output ```bash 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** ```bash 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** ```bash docmap huge-doc.md --type code --lang go # Every Go snippet docmap huge-doc.md --type callout --kind warning # Every warning ``` **Workflow: understand changes** ```bash git checkout feature-branch docmap docs/api.md --since main # What did this PR change? ``` **Workflow: project-wide discovery** ```bash 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** ```bash 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 ```bash 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.