Add --refs flag to show markdown cross-references

Like codemap's --deps, this shows how docs link to each other:
- Finds all [text](file.md) links between markdown files
- Shows HUBS (most referenced docs)
- Displays reference flow graph

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: JordanCoin

README.md

@@ -66,6 +66,7 @@ docmap README.md                  # Single file deep dive
 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
@@ -122,6 +123,33 @@ See the actual content:
 docmap docs/API.md --expand "Authentication"
 ```
 
+### References Mode
+
+See how docs link to each other (like `codemap --deps`):
+
+```bash
+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 |

main.go

@@ -12,7 +12,7 @@ import (
 
 func main() {
 	if len(os.Args) < 2 {
-		fmt.Println("Usage: docmap <file.md|dir> [--section <name>] [--expand <name>]")
+		fmt.Println("Usage: docmap <file.md|dir> [--section <name>] [--expand <name>] [--refs]")
 		os.Exit(1)
 	}
 
@@ -21,6 +21,7 @@ func main() {
 	// Parse flags
 	var sectionFilter string
 	var expandSection string
+	var showRefs bool
 	for i := 2; i < len(os.Args); i++ {
 		switch os.Args[i] {
 		case "--section", "-s":
@@ -33,6 +34,8 @@ func main() {
 				expandSection = os.Args[i+1]
 				i++
 			}
+		case "--refs", "-r":
+			showRefs = true
 		}
 	}
 
@@ -50,7 +53,11 @@ func main() {
 			fmt.Println("No markdown files found")
 			os.Exit(1)
 		}
-		render.MultiTree(docs, target)
+		if showRefs {
+			render.RefsTree(docs, target)
+		} else {
+			render.MultiTree(docs, target)
+		}
 	} else {
 		// Single file mode
 		content, err := os.ReadFile(target)

parser/markdown.go

@@ -10,6 +10,14 @@ type Document struct {
 	Filename    string
 	TotalTokens int
 	Sections    []*Section
+	References  []Reference // Links to other .md files
+}
+
+// Reference represents a link to another markdown file
+type Reference struct {
+	Text   string // Link text
+	Target string // Target file path
+	Line   int    // Line number where reference appears
 }
 
 // Section represents a heading and its content
@@ -36,12 +44,28 @@ func Parse(content string) *Document {
 	doc := &Document{}
 
 	headingRe := regexp.MustCompile(`^(#{1,6})\s+(.+)$`)
+	// Match markdown links to .md files: [text](path.md) or [text](path.md#anchor)
+	linkRe := regexp.MustCompile(`\[([^\]]+)\]\(([^)]+\.md(?:#[^)]*)?)\)`)
 
 	var allSections []*Section
 	var currentSection *Section
 	var contentBuilder strings.Builder
 
 	for i, line := range lines {
+		// Extract markdown links to .md files
+		for _, match := range linkRe.FindAllStringSubmatch(line, -1) {
+			target := match[2]
+			// Remove anchor if present
+			if idx := strings.Index(target, "#"); idx != -1 {
+				target = target[:idx]
+			}
+			doc.References = append(doc.References, Reference{
+				Text:   match[1],
+				Target: target,
+				Line:   i + 1,
+			})
+		}
+
 		if matches := headingRe.FindStringSubmatch(line); matches != nil {
 			// Save previous section's content
 			if currentSection != nil {

render/tree.go

@@ -261,3 +261,119 @@ func getTopSections(sections []*parser.Section, maxDepth int) []*parser.Section
 	}
 	return result
 }
+
+// RefsTree renders document references (links to other .md files)
+func RefsTree(docs []*parser.Document, dirName string) {
+	// Build reference graph
+	type RefInfo struct {
+		From   string
+		To     string
+		Text   string
+		Line   int
+	}
+
+	var allRefs []RefInfo
+	fileRefs := make(map[string][]string)     // file -> files it references
+	fileRefBy := make(map[string][]string)    // file -> files that reference it
+
+	for _, doc := range docs {
+		for _, ref := range doc.References {
+			allRefs = append(allRefs, RefInfo{
+				From: doc.Filename,
+				To:   ref.Target,
+				Text: ref.Text,
+				Line: ref.Line,
+			})
+			fileRefs[doc.Filename] = append(fileRefs[doc.Filename], ref.Target)
+			fileRefBy[ref.Target] = append(fileRefBy[ref.Target], doc.Filename)
+		}
+	}
+
+	if len(allRefs) == 0 {
+		fmt.Println("No markdown cross-references found")
+		return
+	}
+
+	// Header
+	innerWidth := 60
+	titleLine := fmt.Sprintf(" %s/ ", dirName)
+	padding := innerWidth - len(titleLine)
+	leftPad := padding / 2
+	rightPad := padding - leftPad
+	fmt.Printf("╭%s%s%s╮\n", strings.Repeat("─", leftPad), titleLine, strings.Repeat("─", rightPad))
+
+	info := fmt.Sprintf("References: %d links between docs", len(allRefs))
+	fmt.Printf("│ %-*s │\n", innerWidth-2, centerText(info, innerWidth-2))
+	fmt.Printf("╰%s╯\n", strings.Repeat("─", innerWidth))
+	fmt.Println()
+
+	// Find hubs (most referenced files)
+	type hub struct {
+		file  string
+		count int
+	}
+	var hubs []hub
+	for file, refs := range fileRefBy {
+		if len(refs) >= 2 {
+			hubs = append(hubs, hub{file, len(refs)})
+		}
+	}
+
+	if len(hubs) > 0 {
+		// Sort by count descending
+		for i := 0; i < len(hubs); i++ {
+			for j := i + 1; j < len(hubs); j++ {
+				if hubs[j].count > hubs[i].count {
+					hubs[i], hubs[j] = hubs[j], hubs[i]
+				}
+			}
+		}
+
+		fmt.Printf("%sHUBS:%s ", bold, reset)
+		var hubStrs []string
+		for _, h := range hubs {
+			if len(hubStrs) >= 5 {
+				break
+			}
+			hubStrs = append(hubStrs, fmt.Sprintf("%s%s%s (%d←)", green, h.file, reset, h.count))
+		}
+		fmt.Println(strings.Join(hubStrs, ", "))
+		fmt.Println()
+	}
+
+	// Show reference flow by file
+	fmt.Printf("%sReference Flow:%s\n", bold+cyan, reset)
+	fmt.Println()
+
+	// Group by source file
+	printed := make(map[string]bool)
+	for _, doc := range docs {
+		if len(doc.References) == 0 {
+			continue
+		}
+		if printed[doc.Filename] {
+			continue
+		}
+		printed[doc.Filename] = true
+
+		// Dedupe targets
+		seen := make(map[string]bool)
+		var targets []string
+		for _, ref := range doc.References {
+			if !seen[ref.Target] {
+				targets = append(targets, ref.Target)
+				seen[ref.Target] = true
+			}
+		}
+
+		fmt.Printf("  %s%s%s\n", bold, doc.Filename, reset)
+		for i, target := range targets {
+			connector := "├──▶ "
+			if i == len(targets)-1 {
+				connector = "└──▶ "
+			}
+			fmt.Printf("  %s%s%s%s\n", dim, connector, reset, target)
+		}
+		fmt.Println()
+	}
+}