Feature Request: Markdown Link Graph Visualization (JSON/Mermaid)

[Mearman]

Feature Request: Markdown Link Graph Visualization (JSON/Mermaid)

Problem

Understanding the interconnections between markdown files in complex documentation projects is challenging. Users need visual representations of how files link to each other to better understand information architecture and identify connectivity patterns.

Proposed Solution

Add functionality to generate interactive link graphs from markdown file relationships, exportable as JSON data or embeddable Mermaid diagrams.

Core Features

1. Link Graph Generation

• Parse all markdown files to extract internal links
• Build directed graph of file relationships
• Support different link types (relative, absolute, anchors)
• Include bidirectional relationship mapping
• Track link strength (frequency of references)

2. Multiple Output Formats

• JSON Graph: Machine-readable format for external tools
• Mermaid Diagrams: Embeddable in markdown files
• Interactive HTML: Clickable graph with zoom/pan
• GraphViz DOT: Professional graph layout format

3. Graph Analysis

• Identify hub files (highly connected)
• Find orphaned files (no incoming links)
• Detect circular references
• Calculate centrality metrics
• Highlight broken link paths

4. Embedding Capabilities

• Auto-inject Mermaid diagrams into README files
• Generate graph sections for documentation
• Update graphs when file structure changes
• Support filtered views (by directory, file type, etc.)

Use Cases

1. Architecture Understanding: Visualize information flow in documentation
2. Navigation Design: Identify key hub files for menu structures
3. Content Planning: Find gaps and over-connected areas
4. Refactoring Support: Understand impact of moving/renaming files
5. Documentation Health: Spot isolated or poorly connected content

Suggested API

// Generate link graph
const graph = await generateLinkGraph('./docs', {
  format: 'json' | 'mermaid' | 'html' | 'dot',
  includeAnchors: true,
  filterBrokenLinks: false,
  maxDepth: 5
});

// Embed in markdown files
await embedLinkGraph('./docs/README.md', {
  graphType: 'mermaid',
  section: 'Documentation Structure',
  filterPattern: './guides/**/*.md'
});

// Generate interactive visualization
await buildInteractiveGraph('./docs', './output/graph.html', {
  includeMetrics: true,
  enableSearch: true,
  colorByDirectory: true
});

// Analyze graph properties
const analysis = await analyzeLinkGraph('./docs', {
  detectOrphans: true,
  calculateCentrality: true,
  findCycles: true
});

Example Outputs

Mermaid Diagram (embeddable in markdown)

graph TD
    A[README.md] --> B[getting-started.md]
    A --> C[api-reference.md]
    B --> D[installation.md]
    B --> E[configuration.md]
    C --> F[endpoints.md]
    C --> G[authentication.md]
    D --> H[troubleshooting.md]
    E --> H
    F --> G
    
    style A fill:#e1f5fe
    style H fill:#fff3e0
    style C fill:#f3e5f5

Loading

JSON Graph Structure

{
  "nodes": [
    {
      "id": "README.md",
      "path": "./README.md",
      "title": "Project Overview",
      "wordCount": 1250,
      "incomingLinks": 0,
      "outgoingLinks": 5,
      "centrality": 0.85
    }
  ],
  "edges": [
    {
      "source": "README.md",
      "target": "getting-started.md",
      "weight": 2,
      "linkType": "relative",
      "anchor": null
    }
  ],
  "metrics": {
    "totalNodes": 12,
    "totalEdges": 18,
    "orphanedNodes": 1,
    "circularReferences": 0,
    "averageConnectivity": 1.5
  }
}

Analysis Report

📊 Link Graph Analysis:
- Total files: 12
- Total connections: 18
- Hub files: README.md (5 outgoing), api-reference.md (8 incoming)
- Orphaned files: changelog.md
- Circular references: None detected
- Average path length: 2.3 steps
- Most central: api-reference.md (centrality: 0.92)

Integration with Existing Features

• File Moving: Auto-update embedded graphs when files are moved
• Link Validation: Highlight broken connections in graph views
• Documentation Generation: Include graph sections in auto-generated docs
• Tree Visualization: Combine with file tree features for complete overview

Additional Context

This feature would provide crucial insights into documentation architecture, complementing the existing file operations and tree visualization features. The ability to embed graphs directly in markdown files would make the visualizations part of the living documentation.

Graph visualization is essential for understanding complex documentation projects and would position markmv as a comprehensive documentation analysis and management tool.