Adding Documentation

Quick start

To add documentation for a new service:

1. Create the docs directory

Inside your service's app directory, create a docs/ folder with a docs.config.ts file:

apps/{your-service}/docs/
├── docs.config.ts
├── overview.md
└── any-other-page.md

2. Define docs.config.ts

import type { DocsServiceConfig } from "../../src/lib/docs-config";

export const config: DocsServiceConfig = {
    service: "your-service", // URL-safe identifier
    title: "Your Service", // Sidebar section header
    icon: "shield", // Lucide icon name
    order: 10, // Sort position (lower = higher in sidebar)
};

3. Write markdown files

Each .md file needs YAML front-matter at the top:

---
title: "Page Title"
description: "Optional subtitle"
order: 0
audience: "external"
---

Your markdown content here...

The filename (without .md) becomes the URL slug. For example, integration-guide.md produces the route /docs/your-service/integration-guide.

4. Run the discovery script

cd apps/documentation
pnpm discover-docs

This generates docs-manifest.json which the app reads at build time to construct navigation and routes.

5. Verify locally

pnpm dev

Open http://localhost:3010 and check that your service appears in the sidebar.

For services on other branches

If your service lives on a separate branch (e.g. a feature branch not yet merged to main), add it to the DOC_SOURCES array in scripts/fetch-docs.ts. The build-time fetcher will pull the docs from your branch using git show.

File naming conventions

• Use kebab-case for filenames: api-reference.md, not API Reference.md
• Keep names short and descriptive
• The filename determines the URL — choose wisely as changing it breaks links