DocsGraph

Storybook for engineering architecture and codebase documentation — auto-generate beautiful docs from markdown files anywhere in your codebase.

What is DocsGraph?

DocsGraph is a codebase knowledge operating system that lets developers place markdown documentation files anywhere inside their codebase and automatically generates a beautiful, searchable documentation dashboard.

The Problem

• Codebases grow huge, architecture becomes opaque
• Documentation lives in wikis, Notion, or Confluence — disconnected from code
• Onboarding is painful, knowledge stays in developers' heads
• Existing tools require manual sidebar config and route registration

The Solution

Drop .md files anywhere in your codebase and get instant, beautiful documentation.

Quick Start

1. Install

npm install -D docsgraph
# or
pnpm add -D docsgraph
# or
yarn add -D docsgraph

2. Initialize

npx docsgraph init

This creates:

• docsgraph.config.ts - Configuration file
• docs/ - Example documentation files
• .docsgraph/ - Cache directory

3. Start the dev server

npx docsgraph dev

Open http://localhost:4000 to see your docs!

4. Add to package.json (optional)

{
  "scripts": {
    "docs": "docsgraph dev",
    "docs:scan": "docsgraph scan"
  }
}

Features

• 📊 Hierarchical sidebar — auto-generated from your docs
• 🔍 Full-text search — Cmd+K instant search
• 🌳 Business-oriented navigation — not filesystem paths
• 🔥 Hot reload — edit docs, see changes instantly
• 🎨 Syntax highlighting — powered by Shiki
• 📈 Knowledge graph — visualize document relationships

Documentation Structure

Place markdown files anywhere in your project:

src/
 ├── homepage/
 │    └── feed/
 │         ├── recommendation-logic.md
 │         ├── ranking.md
 │         └── experiments.md
 └── cart/
      ├── pricing-rules.md
      ├── checkout-flow.md
      └── tax-calculation.md

Frontmatter

Add metadata to your markdown files:

---
title: Payment Retry Edge Cases
sidebarPath: commerce/cart/payments
route: commerce/cart/payment-retries
description: How payment retries work
tags:
  - payments
  - reliability
owners:
  - payments-team
order: 3
---

# Your content here

CLI Commands

# Start dev server with hot reload
npx docsgraph dev

# Scan and list discovered documents
npx docsgraph scan

# Initialize DocsGraph in a project
npx docsgraph init

Configuration

Create docsgraph.config.ts in your project root:

import type { DocsGraphConfig } from 'docsgraph';

const config: Partial<DocsGraphConfig> = {
  title: 'My Docs',
  include: ['**/*.md'],
  exclude: ['node_modules/**', 'dist/**'],
  port: 4000,
  sidebar: {
    sortStrategy: 'alphabetical',
    autoExpandSingleChild: true,
  },
  search: {
    enabled: true,
    maxResults: 20,
  },
};

export default config;

License

MIT

Links

• GitHub
• npm
• Issues