Documentation

The documentation site is built with VitePress and uses TypeDoc for API reference generation. It lives at apps/docs/.

Running Locally

cd apps/docs
pnpm dev

This starts the VitePress dev server with hot reload. Changes to markdown files are reflected immediately.

Building

cd apps/docs
pnpm build

The build pipeline:

1. aggregate-packages.mjs -- Reads each package's README.md and package.json, then generates markdown files in docs/packages/{category}/{name}.md with VitePress frontmatter. This script runs automatically before the VitePress build.
2. VitePress build -- Compiles markdown to static HTML.
3. Pagefind -- Runs post-build to generate a local search index.

To preview the built site:

cd apps/docs
pnpm preview

Site Structure

apps/docs/
├── docs/
│   ├── .vitepress/
│   │   └── config.ts          # VitePress configuration (nav, sidebar, theme)
│   ├── index.md               # Landing page
│   ├── introduction/          # What is Web Engine Dev, philosophy, features
│   ├── getting-started/       # Installation, quick start, first game
│   ├── concepts/              # Core concepts (ECS, rendering, physics, ...)
│   ├── guides/                # In-depth guides by topic
│   ├── packages/              # Auto-generated from package READMEs
│   ├── editor/                # Editor documentation
│   ├── architecture/          # Architecture and design decisions
│   ├── contributing/          # Developer setup, conventions, testing
│   └── api/                   # TypeDoc API reference (generated)
├── scripts/
│   └── aggregate-packages.mjs # Package README aggregation script
└── package.json

Writing New Pages

1. Create the Markdown File

Add a .md file in the appropriate directory under docs/. Every page should start with YAML frontmatter:

---
title: My Page Title
description: A brief description for SEO and link previews.
---

# My Page Title

Content goes here.

2. Add to Sidebar

Edit docs/.vitepress/config.ts to add your page to the sidebar navigation. Sidebar entries are grouped by directory:

'/my-section/': [
  {
    text: 'My Section',
    items: [
      { text: 'Overview', link: '/my-section/overview' },
      { text: 'New Page', link: '/my-section/new-page' },  // Add here
    ],
  },
],

3. Add to Navigation (Optional)

If adding a new top-level section, add a nav entry in the same config file:

nav: [
  { text: 'My Section', link: '/my-section/overview' },
],

Markdown Features

VitePress supports standard Markdown plus several extensions.

Code Blocks

Use fenced code blocks with language identifiers. TypeScript examples should be practical and runnable:

```typescript
import { createWorld, defineComponent } from '@web-engine-dev/ecs';

const Position = defineComponent({ x: 'f32', y: 'f32' });
const world = createWorld();
```

Custom Containers

VitePress supports tip, warning, danger, info, and details containers:

::: tip
Helpful tip content.
:::

::: warning
Important warning.
:::

::: danger
Critical information.
:::

::: info
Informational note.
:::

::: details Click to expand
Hidden content revealed on click.
:::

Tables

Standard Markdown tables are supported:

| Package | Layer | Purpose |
|---------|-------|---------|
| `@web-engine-dev/ecs` | 1 | Entity Component System |
| `@web-engine-dev/renderer` | 7 | Rendering pipeline |

Package Documentation

Package pages are auto-generated from README.md files by the aggregate-packages.mjs script. To document a package:

1. Write a comprehensive README.md in the package root
2. Include a description field in package.json
3. Run pnpm build:packages (or the full docs build) to regenerate

The script adds VitePress frontmatter with the package name, description, and category.

API Reference (TypeDoc)

API documentation is generated from TSDoc comments in source code using TypeDoc with the typedoc-plugin-markdown plugin. The generated output goes into docs/api/.

TSDoc Conventions

Public APIs should include comprehensive TSDoc:

/**
 * Creates a new ECS world instance.
 *
 * @param options - Configuration options for the world
 * @returns A new World instance ready for entity creation
 * @throws {Error} If the maximum entity count is exceeded
 *
 * @example
 * ```typescript
 * const world = createWorld({ maxEntities: 10000 });
 * const entity = world.spawn();
 * ```
 *
 * @remarks
 * The world uses archetype-based SoA storage internally.
 * Entity IDs are recycled after despawn with generation tracking.
 */
export function createWorld(options?: WorldOptions): World {
  // ...
}

Key tags to include:

Tag	When to Use
@param	Every parameter
@returns	Every non-void return
@throws	Every error condition
@example	At least one usage example for public APIs
@remarks	Complexity guarantees, invariants, important implementation notes
@see	Links to related APIs or documentation
@deprecated	When marking for removal (include migration path)

Search

The site uses Pagefind for local search. The search index is generated post-build and requires no external service. Search is available via the search bar in the top navigation.

Style Guidelines

• Be practical: Focus on working code examples over abstract descriptions
• Be specific: Reference actual types, function names, and package paths
• Be honest: Document what exists and works, not aspirational features
• Keep it current: Update documentation when APIs or behavior changes
• Link between pages: Use relative links to connect related topics
• Use tables for reference: Tabular data is easier to scan than prose lists