🗺️ docmap

docmap — instant documentation structure for LLMs and humans. Navigate massive docs without burning tokens.

The Problem

Documentation files are everywhere — READMEs, design docs, changelogs, API references, PDFs. But:

• LLMs can't open large markdown files or PDFs (token limits)
• Humans have to open each file to see what's inside
• There's no "file tree" for documentation content

The Solution

docmap .

╭─────────────────────── docs/ ───────────────────────╮
│      22 files | 645 sections | ~109.2k tokens       │
╰─────────────────────────────────────────────────────╯

├── README.md (3.8k)
│   ├─ Project Overview
│   ├─ Installation
│   └─ Quick Start
├── docs/ARCHITECTURE.md (7.7k)
│   ├─ System Design
│   ├─ Component Details
│   └─ Data Flow
├── docs/API.md (12.1k)
│   ├─ Authentication
│   ├─ Endpoints
│   └─ Error Handling
└── CHANGELOG.md (15.2k)
    ├─ v2.0.0
    ├─ v1.5.0
    └─ v1.0.0

One command. Instant structure. No LLM needed.

Install

# macOS/Linux
brew tap JordanCoin/tap && brew install docmap

# Windows
scoop bucket add docmap https://github.com/JordanCoin/scoop-docmap
scoop install docmap

Other options: Releases | go install github.com/JordanCoin/docmap@latest

Usage

docmap .                          # All markdown and PDF files in directory
docmap README.md                  # Single markdown file deep dive
docmap report.pdf                 # Single PDF file structure
docmap docs/                      # Specific folder
docmap README.md --section "API"  # Filter to section
docmap README.md --expand "API"   # Show section content
docmap . --refs                   # Show cross-references between docs

Output

Directory Mode

Map all markdown and PDF files in a project:

docmap /path/to/project

Shows each file with token count and top-level sections.

Single File Mode

Deep dive into one document:

docmap docs/ARCHITECTURE.md

╭────────────────── ARCHITECTURE.md ──────────────────╮
│           33 sections | ~7.7k tokens                │
╰─────────────────────────────────────────────────────╯

├── System Design (2.1k)
│   ├── Vision
│   ├── Core Principles
│   │   └─ "Headless-first", "Plan before execute"
│   └── Architecture Overview
├── Components (3.2k)
│   ├── Scheduler
│   ├── Orchestrator
│   └── Memory (RAG)
└── Security (1.4k)
    └─ "SSH keys only", "Human gates"

Section Filter

Zoom into a specific section:

docmap docs/API.md --section "Authentication"

Expand Section

See the actual content:

docmap docs/API.md --expand "Authentication"

PDF Support

Map PDF documents by their outline (table of contents):

docmap report.pdf

╭──────────────────── report.pdf ────────────────────╮
│             Sections: 7 | ~16.9k tokens            │
╰────────────────────────────────────────────────────╯

└── Claude Code-Powered Writing Editor (9.1k)
    ├── Introduction and Feasibility Overview (1.3k)
    ├── Key Features and Benefits (1.3k)
    ├── Designing the Interface (1.3k)
    └── Development Steps (1.3k)

Note: For PDFs with outlines/bookmarks, docmap shows the document structure with estimated token distribution. For PDFs without outlines, it falls back to page-by-page structure. Scanned/image-only PDFs will show a page count but no text content.

References Mode

See how docs link to each other (like codemap --deps):

docmap . --refs

╭─────────────────────── project/ ───────────────────────╮
│              References: 53 links between docs         │
╰────────────────────────────────────────────────────────╯

HUBS: docs/architecture.md (5←), docs/api.md (3←)

Reference Flow:

  README.md
  ├──▶ docs/architecture.md
  ├──▶ docs/api.md
  └──▶ CHANGELOG.md

  docs/architecture.md
  ├──▶ docs/components.md
  └──▶ docs/data-flow.md

Why docmap?

Before	After
"Read this 100k token doc"	"Here's the structure, ask for what you need"
Open 20 files to find something	See all sections at a glance
Scroll through giant CHANGELOGs	Jump to the version you need
Guess what's in each doc	Token counts show what's meaty

Sister Tool

docmap is the documentation companion to codemap:

codemap .   # code structure
docmap .    # doc structure

Together: complete spatial awareness of any repository.

How It Works

Markdown:

1. Parse headings into a tree structure
2. Estimate tokens per section (~4 chars/token)
3. Extract key terms (bold text, inline code)
4. Render as a navigable tree

PDF:

1. Extract outline/bookmarks if available, otherwise use pages
2. Parse text content from each page
3. Estimate tokens (~4 chars/token)
4. Render as a navigable tree

No API calls. Just fast, local parsing.

Roadmap

Ideas for future versions:

• Depth control (--depth 2) — Limit heading levels shown, e.g., only h1/h2
• Token budget mode (--budget 4000) — Auto-select sections that fit within a token limit
• JSON output (--json) — Machine-readable output for piping and parsing
• Section previews — Show first ~100 tokens of each section inline

PRs welcome for any of these!

Contributing

1. Fork → 2. Branch → 3. Commit → 4. PR

See CONTRIBUTING.md for details.

License

MIT