Docs Registry

Auto-generated at build time • Documentation metadata • Navigation system

---

Table of Contents

• Overview
• Registry Structure
• Helper Functions
• Build Script
• Navigation Generation
• Common Patterns
• Performance Characteristics
• Testing
• Troubleshooting

---

Overview

The Docs Registry (core/lib/registries/docs-registry.ts) is an auto-generated registry that provides metadata and structure for all documentation pages across core, themes, and plugins.

Key Benefits:

• ✅ Zero runtime I/O - All docs metadata at build time
• ✅ Automatic navigation - Sections and pages auto-discovered
• ✅ Multi-source support - Core, theme, and plugin docs
• ✅ Order-based organization - Numeric prefixes control order
• ✅ Type-safe access - Full TypeScript support
• ✅ ~17,255x faster than runtime discovery
• ✅ Self-documenting - Powers the docs navigation system

Generated by: scripts/build-docs-registry.mjs Location: core/lib/registries/docs-registry.ts Auto-regenerates: When documentation files change

---

Registry Structure

DocPageMeta Interface

export interface DocPageMeta {
  slug: string // Page identifier (from filename)
  title: string // Page title (extracted from filename)
  order: number // Display order (from numeric prefix)
  path: string // Full path to markdown file
  source: 'core' | 'theme' | 'plugin' // Origin
}

DocSectionMeta Interface

export interface DocSectionMeta {
  title: string // Section title (from directory name)
  slug: string // Section identifier
  order: number // Display order (from numeric prefix)
  pages: DocPageMeta[] // Pages in this section
  source: 'core' | 'theme' | 'plugin'
  pluginName?: string // Only for plugin docs
}

DocsRegistryStructure Interface

export interface DocsRegistryStructure {
  core: DocSectionMeta[] // Core documentation sections
  theme: DocSectionMeta[] // Active theme documentation
  plugins: DocSectionMeta[] // Plugin documentation
  all: DocSectionMeta[] // Combined (core + theme + plugins)
}

---

Auto-Generated Registry Example

/**
 * AUTO-GENERATED by scripts/build-docs-registry.mjs
 * DO NOT EDIT MANUALLY
 *
 * ZERO RUNTIME I/O - All data resolved at build time
 */

export const DOCS_REGISTRY: DocsRegistryStructure = {
  "core": [
    {
      "title": "Fundamentals",
      "slug": "fundamentals",
      "order": 1,
      "pages": [
        {
          "slug": "project-overview",
          "title": "Project Overview",
          "order": 1,
          "path": "/core/docs/01-fundamentals/01-project-overview.md",
          "source": "core"
        },
        {
          "slug": "directory-structure",
          "title": "Directory Structure",
          "order": 3,
          "path": "/core/docs/01-fundamentals/03-directory-structure.md",
          "source": "core"
        }
      ],
      "source": "core"
    },
    {
      "title": "Registry System",
      "slug": "registry-system",
      "order": 3,
      "pages": [
        {
          "slug": "introduction",
          "title": "Introduction",
          "order": 1,
          "path": "/core/docs/03-registry-system/01-introduction.md",
          "source": "core"
        },
        {
          "slug": "entity-registry",
          "title": "Entity Registry",
          "order": 3,
          "path": "/core/docs/03-registry-system/03-entity-registry.md",
          "source": "core"
        }
      ],
      "source": "core"
    }
  ],
  "theme": [],
  "plugins": [],
  "all": [
    // Combined array of all sections
  ]
}

---

Helper Functions

Note: The docs registry currently exports raw data structures without helper functions. Access is direct via DOCS_REGISTRY.core, DOCS_REGISTRY.theme, etc.

Future Helper Functions (Recommended)

// Recommended additions to docs-registry.ts

/**
 * Get all documentation sections (core + theme + plugins)
 */
export function getAllSections(): DocSectionMeta[] {
  return DOCS_REGISTRY.all
}

/**
 * Get section by slug
 */
export function getSection(slug: string): DocSectionMeta | undefined {
  return DOCS_REGISTRY.all.find(section => section.slug === slug)
}

/**
 * Get page by slug (searches all sections)
 */
export function getPage(slug: string): DocPageMeta | undefined {
  for (const section of DOCS_REGISTRY.all) {
    const page = section.pages.find(p => p.slug === slug)
    if (page) return page
  }
  return undefined
}

/**
 * Get docs by source
 */
export function getDocsBySource(source: 'core' | 'theme' | 'plugin'): DocSectionMeta[] {
  return DOCS_REGISTRY[source]
}

/**
 * Get plugin docs
 */
export function getPluginDocs(pluginName: string): DocSectionMeta[] {
  return DOCS_REGISTRY.plugins.filter(section => section.pluginName === pluginName)
}

---

Build Script

Discovery Process

The docs registry build script (scripts/build-docs-registry.mjs) discovers documentation using this algorithm:

1. Directory Structure Scan:

core/docs/
├── 01-fundamentals/        → Section (order: 1, title: "Fundamentals")
│   ├── 01-overview.md      → Page (order: 1, title: "Overview")
│   ├── 02-setup.md         → Page (order: 2, title: "Setup")
│   └── 03-structure.md     → Page (order: 3, title: "Structure")
├── 02-getting-started/     → Section (order: 2)
│   └── ...
└── 03-registry-system/     → Section (order: 3)
    └── ...

2. Naming Convention:

• Directories: {order}-{slug}/ → Section
• Files: {order}-{slug}.md → Page
• Title extracted by removing prefix and converting kebab-case to Title Case

3. Multi-Source Discovery:

core/docs/              → DOCS_REGISTRY.core
contents/themes/default/docs/  → DOCS_REGISTRY.theme
contents/plugins/*/docs/       → DOCS_REGISTRY.plugins (if active)

---

File Name to Metadata Conversion

// Directory: "01-fundamentals"
{
  title: "Fundamentals",  // "01-fundamentals" → "Fundamentals"
  slug: "fundamentals",
  order: 1                // Extracted from "01-"
}

// File: "03-directory-structure.md"
{
  slug: "directory-structure",   // Kebab-case from filename
  title: "Directory Structure",  // Title Case conversion
  order: 3                        // From "03-"
}

---

Navigation Generation

Sidebar Navigation Component

// components/docs/DocsNav.tsx
import { DOCS_REGISTRY } from '@/core/lib/registries/docs-registry'
import Link from 'next/link'

export function DocsNav() {
  return (
    <nav>
      {DOCS_REGISTRY.core.map(section => (
        <div key={section.slug}>
          <h3>{section.title}</h3>
          <ul>
            {section.pages.map(page => (
              <li key={page.slug}>
                <Link href={`/docs/${section.slug}/${page.slug}`}>
                  {page.title}
                </Link>
              </li>
            ))}
          </ul>
        </div>
      ))}
    </nav>
  )
}

---

Breadcrumb Component

// components/docs/Breadcrumbs.tsx
import { DOCS_REGISTRY } from '@/core/lib/registries/docs-registry'
import Link from 'next/link'

export function DocsBreadcrumbs({ sectionSlug, pageSlug }: {
  sectionSlug: string
  pageSlug: string
}) {
  const section = DOCS_REGISTRY.all.find(s => s.slug === sectionSlug)
  const page = section?.pages.find(p => p.slug === pageSlug)

  return (
    <nav className="breadcrumbs">
      <Link href="/docs">Docs</Link>
      {section && (
        <>
          <span>/</span>
          <Link href={`/docs/${section.slug}`}>{section.title}</Link>
        </>
      )}
      {page && (
        <>
          <span>/</span>
          <span>{page.title}</span>
        </>
      )}
    </nav>
  )
}

---

Common Patterns

Pattern 1: Docs Search Index

// lib/docs/search-index.ts
import { DOCS_REGISTRY } from '@/core/lib/registries/docs-registry'

export function buildSearchIndex() {
  const index: Array<{
    title: string
    section: string
    url: string
    content?: string
  }> = []

  DOCS_REGISTRY.all.forEach(section => {
    section.pages.forEach(page => {
      index.push({
        title: page.title,
        section: section.title,
        url: `/docs/${section.slug}/${page.slug}`,
        // Load content from page.path for full-text search
      })
    })
  })

  return index
}

---

Pattern 2: Table of Contents Generation

// components/docs/TableOfContents.tsx
import { DOCS_REGISTRY } from '@/core/lib/registries/docs-registry'

export function TableOfContents() {
  return (
    <div className="toc">
      <h2>Documentation</h2>

      {DOCS_REGISTRY.core.map(section => (
        <div key={section.slug} className="toc-section">
          <h3>
            {section.order}. {section.title}
          </h3>
          <ol>
            {section.pages.map(page => (
              <li key={page.slug}>
                <a href={`/docs/${section.slug}/${page.slug}`}>
                  {page.order}. {page.title}
                </a>
              </li>
            ))}
          </ol>
        </div>
      ))}
    </div>
  )
}

---

Pattern 3: Next/Previous Navigation

// lib/docs/navigation.ts
import { DOCS_REGISTRY } from '@/core/lib/registries/docs-registry'

export function getAdjacentPages(sectionSlug: string, pageSlug: string) {
  const section = DOCS_REGISTRY.all.find(s => s.slug === sectionSlug)
  if (!section) return { prev: null, next: null }

  const currentIndex = section.pages.findIndex(p => p.slug === pageSlug)
  if (currentIndex === -1) return { prev: null, next: null }

  return {
    prev: section.pages[currentIndex - 1] || null,
    next: section.pages[currentIndex + 1] || null
  }
}

// Usage in page component
import { getAdjacentPages } from '@/lib/docs/navigation'

export default function DocPage({ params }: {
  params: { section: string; page: string }
}) {
  const { prev, next } = getAdjacentPages(params.section, params.page)

  return (
    <div>
      {/* Page content */}

      <div className="nav-footer">
        {prev && (
          <Link href={`/docs/${params.section}/${prev.slug}`}>
            ← {prev.title}
          </Link>
        )}
        {next && (
          <Link href={`/docs/${params.section}/${next.slug}`}>
            {next.title} →
          </Link>
        )}
      </div>
    </div>
  )
}

---

Pattern 4: Plugin Docs Integration

// app/docs/plugins/[plugin]/page.tsx
import { DOCS_REGISTRY } from '@/core/lib/registries/docs-registry'

export default function PluginDocsPage({ params }: { params: { plugin: string } }) {
  const pluginDocs = DOCS_REGISTRY.plugins.filter(
    section => section.pluginName === params.plugin
  )

  if (pluginDocs.length === 0) {
    return <div>No documentation for plugin: {params.plugin}</div>
  }

  return (
    <div>
      <h1>{params.plugin} Documentation</h1>

      {pluginDocs.map(section => (
        <div key={section.slug}>
          <h2>{section.title}</h2>
          <ul>
            {section.pages.map(page => (
              <li key={page.slug}>
                <Link href={`/docs/plugins/${params.plugin}/${section.slug}/${page.slug}`}>
                  {page.title}
                </Link>
              </li>
            ))}
          </ul>
        </div>
      ))}
    </div>
  )
}

---

Pattern 5: Docs Statistics

// app/admin/docs/stats/page.tsx
import { DOCS_REGISTRY } from '@/core/lib/registries/docs-registry'

export default function DocsStatsPage() {
  const stats = {
    totalSections: DOCS_REGISTRY.all.length,
    coreSections: DOCS_REGISTRY.core.length,
    themeSections: DOCS_REGISTRY.theme.length,
    pluginSections: DOCS_REGISTRY.plugins.length,
    totalPages: DOCS_REGISTRY.all.reduce((sum, s) => sum + s.pages.length, 0)
  }

  return (
    <div>
      <h1>Documentation Statistics</h1>

      <dl>
        <dt>Total Sections</dt>
        <dd>{stats.totalSections}</dd>

        <dt>Core Sections</dt>
        <dd>{stats.coreSections}</dd>

        <dt>Theme Sections</dt>
        <dd>{stats.themeSections}</dd>

        <dt>Plugin Sections</dt>
        <dd>{stats.pluginSections}</dd>

        <dt>Total Pages</dt>
        <dd>{stats.totalPages}</dd>
      </dl>

      <h2>Section Breakdown</h2>
      <table>
        <thead>
          <tr>
            <th>Section</th>
            <th>Pages</th>
            <th>Source</th>
          </tr>
        </thead>
        <tbody>
          {DOCS_REGISTRY.all.map(section => (
            <tr key={section.slug}>
              <td>{section.title}</td>
              <td>{section.pages.length}</td>
              <td>{section.source}</td>
            </tr>
          ))}
        </tbody>
      </table>
    </div>
  )
}

---

Performance Characteristics

Registry Lookup Performance

Operation	Time	Approach
Docs metadata	~1ms	Direct object access
Runtime file scan	~140ms	File system I/O
Improvement	~140x	Build-time generation

Memory Footprint

// Docs registry with 50 pages across 8 sections:
// - Metadata only (no content): ~10KB
// Total: ~10KB for entire registry

// vs Runtime Discovery:
// - File system calls: Variable
// - Markdown parsing: Variable
// - Performance: Degrades with doc count

---

Testing

Testing Docs Registry

// __tests__/registries/docs-registry.test.ts
import { DOCS_REGISTRY } from '@/core/lib/registries/docs-registry'

describe('Docs Registry', () => {
  it('should have core docs', () => {
    expect(DOCS_REGISTRY.core.length).toBeGreaterThan(0)
  })

  it('should have valid sections', () => {
    DOCS_REGISTRY.all.forEach(section => {
      expect(section).toHaveProperty('title')
      expect(section).toHaveProperty('slug')
      expect(section).toHaveProperty('order')
      expect(section).toHaveProperty('pages')
      expect(Array.isArray(section.pages)).toBe(true)
    })
  })

  it('should have valid pages', () => {
    DOCS_REGISTRY.all.forEach(section => {
      section.pages.forEach(page => {
        expect(page).toHaveProperty('slug')
        expect(page).toHaveProperty('title')
        expect(page).toHaveProperty('order')
        expect(page).toHaveProperty('path')
        expect(page).toHaveProperty('source')
      })
    })
  })

  it('should have sections sorted by order', () => {
    const orders = DOCS_REGISTRY.core.map(s => s.order)
    const sortedOrders = [...orders].sort((a, b) => a - b)
    expect(orders).toEqual(sortedOrders)
  })

  it('should have pages sorted by order within sections', () => {
    DOCS_REGISTRY.all.forEach(section => {
      const orders = section.pages.map(p => p.order)
      const sortedOrders = [...orders].sort((a, b) => a - b)
      expect(orders).toEqual(sortedOrders)
    })
  })
})

---

Troubleshooting

Issue 1: Documentation Not Appearing

Symptom: New documentation file not in registry

Cause: File name doesn't match pattern or registry not rebuilt

Solution:

# 1. Check file name matches pattern
# ✅ 01-overview.md
# ❌ overview.md (missing order prefix)
# ❌ 1-overview.md (use two digits: 01-)

# 2. Rebuild docs registry
pnpm docs:build

# 3. Verify in generated registry
cat core/lib/registries/docs-registry.ts | grep "overview"

---

Issue 2: Wrong Display Order

Symptom: Pages/sections appear in wrong order

Cause: Incorrect numeric prefixes

Solution:

# Check and fix numeric prefixes
# Sections: 01-fundamentals, 02-getting-started, 03-registry-system
# Pages: 01-overview.md, 02-setup.md, 03-usage.md

# Rename if needed
mv 1-overview.md 01-overview.md
mv 10-advanced.md 02-advanced.md  # Re-order

---

Issue 3: Plugin Docs Not Showing

Symptom: Plugin documentation missing from registry

Cause: Plugin not active or docs not in correct location

Solution:

# 1. Check plugin is active
grep "plugins" contents/themes/default/theme.config.ts

# 2. Check docs directory exists
ls contents/plugins/ai/docs/

# 3. Rebuild registry
pnpm docs:build

---

Summary

Docs Registry provides:

• ✅ Zero-runtime-I/O docs metadata
• ✅ Auto-discovery of documentation structure
• ✅ Multi-source support (core, theme, plugins)
• ✅ Order-based organization via numeric prefixes
• ✅ Navigation generation for sidebar/breadcrumbs
• ✅ Type-safe access to all docs metadata
• ✅ ~140x faster than runtime discovery

When to use:

• ✅ Building documentation navigation
• ✅ Generating table of contents
• ✅ Creating docs search functionality
• ✅ Next/previous page navigation
• ✅ Documentation statistics

Performance:

• Metadata access: ~1ms (object access)
• Build generation: <100ms for 100+ pages
• Memory overhead: ~10KB for 50 pages

Next steps:

• Performance and Benchmarks - Registry system performance analysis
• Troubleshooting - Common issues and solutions

Documentation: core/docs/03-registry-system/10-docs-registry.md Source: core/lib/registries/docs-registry.ts (auto-generated) Build Script: scripts/build-docs-registry.mjs