API Documentation Specification

Overview

Cartographer maintains comprehensive JSDoc/TSDoc coverage across all public APIs, providing the foundation for auto-generated API reference documentation. This specification outlines how to generate, integrate, and maintain API documentation using TypeDoc’s Markdown plugin within the Atlas (Starlight) documentation site.

Status: Active implementation guide

Why Auto-Generate API Docs

Benefits

Single Source of Truth: Documentation lives in code comments, stays in sync with implementation
Searchable API Reference: Developers can quickly find function signatures, parameters, return types, and examples
Type Safety: TSDoc comments are validated during development (TypeScript catches documentation errors)
Maintainability: Update code → update comment → regenerate docs (automated)
Professional Appearance: Auto-generated documentation looks polished and consistent
Integrated Experience: API docs live alongside user guides in the same site

Architecture: TypeDoc Markdown + Starlight

The Approach

Generate API documentation as Markdown files using TypeDoc’s Markdown plugin, placing them directly in Starlight’s content directory.

Flow:

TypeScript Source Files
         ↓
    TypeDoc generates
         ↓
    Markdown files
         ↓
    Placed in atlas/src/content/docs/reference/api/
         ↓
    Starlight builds complete site
         ↓
    Deploy to GitHub Pages

Why This Approach

TypeDoc with Markdown Plugin:

✅ Best-in-class TypeScript support (understands generics, type unions, etc.)
✅ Generates clean Markdown files
✅ Perfect integration with Starlight
✅ Excellent type inference from source code
✅ Native content format for Starlight

Starlight Integration:

✅ API docs use same theme as user guides
✅ Unified navigation and search
✅ Consistent branding across all documentation
✅ Single deployment process
✅ No iframe or context switching

Implementation

1. Install Dependencies

pnpm add -D typedoc typedoc-plugin-markdown

2. Create TypeDoc Configuration

typedoc.json:

{
  "$schema": "https://typedoc.org/schema.json",
  "entryPoints": ["src/index.ts"],
  "out": "atlas/src/content/docs/reference/api",
  "plugin": ["typedoc-plugin-markdown"],
  "readme": "none",
  "excludePrivate": true,
  "excludeInternal": true,
  "excludeExternals": true,
  "hideGenerator": true,
  "sanitizeComments": true,
  "sort": ["source-order"],
  "kindSortOrder": [
    "Function",
    "Class",
    "Interface",
    "TypeAlias",
    "Variable"
  ]
}

3. Add Build Scripts

package.json:

{
  "scripts": {
    "docs:api": "typedoc",
    "prebuild:atlas": "pnpm docs:api"
  }
}

4. Output Structure

TypeDoc will generate:

atlas/src/content/docs/reference/api/
├── index.md                    # API overview
├── modules.md                  # All modules
├── functions/
│   ├── filterByTag.md
│   ├── sortByDate.md
│   └── ...
├── interfaces/
│   ├── CatalogSchema.md
│   ├── Library.md
│   └── ...
└── types/
    ├── CatalogItem.md
    └── ...

5. Create API Overview Page

atlas/src/content/docs/reference/index.mdx:

---
title: API Reference
description: Complete API documentation for Cartographer
---

Welcome to the Cartographer API reference. This section documents all public APIs, including functions, interfaces, and types.

## Quick Links

- [Functions](/reference/api/functions/) - All query and utility functions
- [Interfaces](/reference/api/interfaces/) - Configuration and data interfaces
- [Types](/reference/api/types/) - Type definitions

## Getting Started

New to the API? Start with our [Developer Guide](/developers/) to understand the architecture before diving into specific APIs.

atlas/astro.config.mjs:

starlight({
  sidebar: [
    // ... other sections
    {
      label: 'Reference',
      link: '/reference/',
      items: [
        { label: 'API Overview', link: '/reference/' },
        {
          label: 'API Documentation',
          autogenerate: { directory: 'reference/api' }
        },
      ],
    },
  ],
})

7. Update GitHub Actions

atlas-deploy.yml:

- name: Generate API documentation
  run: pnpm docs:api

- name: Build Atlas
  run: pnpm --filter atlas build

8. Add .gitignore Entry

# Generated API docs
atlas/src/content/docs/reference/api/

The API docs are generated on build, so they shouldn’t be committed.

Customizing TypeDoc Output

Adding Starlight Frontmatter

TypeDoc Markdown output may need frontmatter adjustments. Create a post-processing script:

scripts/process-api-docs.js:

import fs from 'fs';
import path from 'path';
import { glob } from 'glob';

const apiDocsDir = 'atlas/src/content/docs/reference/api';

// Find all generated markdown files
const files = glob.sync(`${apiDocsDir}/**/*.md`);

files.forEach(file => {
  let content = fs.readFileSync(file, 'utf-8');

  // Add Starlight frontmatter if missing
  if (!content.startsWith('---')) {
    const title = path.basename(file, '.md');
    const frontmatter = `---
title: ${title}
description: API documentation for ${title}
---

`;
    content = frontmatter + content;
    fs.writeFileSync(file, content);
  }
});

console.log(`Processed ${files.length} API documentation files`);

Update package.json:

{
  "scripts": {
    "docs:api": "typedoc && node scripts/process-api-docs.js"
  }
}

Custom TypeDoc Theme

If you need more control over Markdown output, you can customize the plugin options:

typedoc.json:

{
  "plugin": ["typedoc-plugin-markdown"],
  "entryDocument": "index.md",
  "hidePageHeader": true,
  "hideBreadcrumbs": false,
  "outputFileStrategy": "members",
  "flattenOutputFiles": false,
  "useCodeBlocks": true
}

Maintenance & Updates

Automatic Regeneration

API docs regenerate automatically:

Developer updates code and TSDoc comments
Commits and pushes to GitHub
GitHub Actions runs pnpm docs:api
TypeDoc regenerates Markdown files
Starlight builds complete site
Deploys to GitHub Pages

Manual Regeneration (Local)

# Regenerate API docs
pnpm docs:api

# View locally
pnpm --filter atlas dev

Quality Checklist

Before releasing updated API docs:

All public exports have TSDoc comments
All @param tags documented
All @returns tags documented
Complex functions have @example tags
No incomplete or @todo documentation
TypeScript compiles cleanly: pnpm run build
API docs generate without errors: pnpm docs:api
Local preview looks correct: pnpm --filter atlas dev

Best Practices

TSDoc Comments

Good:

/**
 * Filters catalog items by tag.
 *
 * @param items - Array of catalog items to filter
 * @param tag - Tag to filter by
 * @returns Filtered array containing only items with the specified tag
 *
 * @example
 * ```typescript
 * const items = getCatalogItems();
 * const filtered = filterByTag(items, 'important');
 * ```
 */
export function filterByTag(items: CatalogItem[], tag: string): CatalogItem[] {
  return items.filter(item => item.tags?.includes(tag));
}

Bad:

// Filters items
export function filterByTag(items: CatalogItem[], tag: string): CatalogItem[] {
  return items.filter(item => item.tags?.includes(tag));
}

Organize by Module

Structure source code to generate logical API documentation sections:

src/
├── index.ts              # Main exports
├── query/
│   ├── filters.ts        # Filter functions
│   ├── sorts.ts          # Sort functions
│   └── groups.ts         # Group functions
├── types/
│   └── index.ts          # Type definitions
└── utils/
    └── index.ts          # Utility functions

TypeDoc will organize docs by these modules.

Link Between API Docs and Guides

In your guides, link to specific API documentation:

To filter items by tag, use the [`filterByTag`](/reference/api/functions/filterByTag) function.

In API docs, link back to guides:

/**
 * For usage examples, see the [Filtering Guide](/guides/filtering).
 */

Troubleshooting

TypeDoc fails to generate

Check:

TypeScript compiles: pnpm run build
typedoc.json is valid JSON
Entry points exist and are correct
All dependencies installed: pnpm install

Generated Markdown has no frontmatter

Solution: Use the post-processing script (see Customizing TypeDoc Output section)

API docs don’t appear in Starlight