Documentation Guidelines

These standards govern all documentation for the StateLoom project — the VitePress documentation site, README files, inline code docs, and architectural documents.

Documentation Site Stack

Tool	Purpose
VitePress	Static site generator (markdown-first, Vite-powered)
Mermaid	Diagrams (loaded browser-side for zero SSR overhead)
Shiki (built-in)	Syntax highlighting with line highlighting, diffs, collapse, focus

VitePress Configuration

typescript

// docs/.vitepress/config.ts
import { defineConfig } from 'vitepress';
import { withMermaid } from 'vitepress-plugin-mermaid';

export default withMermaid(
  defineConfig({
    title: 'StateLoom',
    description: 'Universal State Management SDK',
    mermaid: {
      theme: 'neutral',
    },
    vite: {
      optimizeDeps: {
        include: ['mermaid'],
      },
    },
    // ...themeConfig
  }),
);

Mermaid: Browser-Side Rendering

Mermaid diagrams are rendered client-side via vitepress-plugin-mermaid. The plugin automatically converts ```mermaid code blocks into <div class="mermaid"> elements and handles dark/light mode switching.

No manual theme setup is required — the plugin injects everything at build time.

Code Highlighting (Shiki)

VitePress's built-in Shiki provides all advanced code block features. Note: Expressive Code is not compatible with VitePress (it requires rehype; VitePress uses markdown-it).

Line highlighting:

markdown

```typescript{3-5}
import { signal } from '@stateloom/core';

// These lines are highlighted
const count = signal(0);
count.set(5);

const other = signal('hello');
```

Inline markers:

markdown

```typescript
const count = signal(0); 
const added = signal(1); 
const removed = signal(2); 
const focused = signal(3); 
const bad = signal(null); 
const risky = signal(-1); 
```

Line numbers and collapsible sections:

markdown

```typescript:line-numbers
// Shows line numbers
const count = signal(0);
```

```typescript:collapsed-lines=12
// Lines after 12 are collapsed by default
```

Code groups with titles:

markdown

::: code-group

```bash [pnpm]
pnpm add @stateloom/core
```

```bash [npm]
npm install @stateloom/core
```

:::

Writing Style

Audience

Primary: Developers adopting StateLoom — ranging from intermediate to senior engineers. Unlike the reference blog (v4.sujeet.pro which targets principal engineers), documentation should be accessible to developers who are productive with JavaScript/TypeScript but may not have deep state management experience.

Voice

Clear and direct: No filler, no hedging
Show, don't tell: Lead with code examples, follow with explanation
Progressive disclosure: Simple usage first, advanced patterns later
Developer empathy: Acknowledge the mental model the reader is coming from (Zustand, Jotai, Redux, etc.)

Principles

Code-first: Every concept must have a runnable code example
Consumer perspective: Document what the developer needs to know, not internal implementation details
Zero-to-productive: A developer should be productive within 5 minutes of reading Getting Started
Migration-friendly: For each paradigm, show the equivalent in the library developers are migrating from
Copy-pasteable: Examples should work when copied directly into a project

Mermaid Diagram Standards

Use Mermaid for all diagrams in documentation. Diagrams should clarify architecture, data flow, and relationships.

When to Use Diagrams

Diagram Type	When
Flowchart (`graph`/`flowchart`)	Data flow, decision trees, pipelines
Sequence diagram	Temporal interactions (reactive notification flow)
Class diagram	Interface relationships, type hierarchies
State diagram	Lifecycle states (signal dirty/clean, store mounted/unmounted)

Diagram Guidelines

Every diagram must have a purpose — don't diagram trivial concepts
Keep diagrams focused: 5–15 nodes maximum
Use descriptive labels, not abbreviations
Prefer left-to-right (LR) or top-to-bottom (TB) orientation
Use subgraphs to group related concepts
Match color coding to layer (blue = core, purple = paradigms, green = adapters)

Examples

Architecture diagram:

Sequence diagram:

Site Structure

The documentation site has four top-level sections, accessible from the navigation bar:

Section	Path Prefix	Purpose
Guide	`/guide/`	Framework adoption guides — getting started, per-framework setup, sample projects
API	`/api/`	Per-package API reference — one page per `@stateloom/*` package
Architecture	`/architecture/`	Design docs — high-level design (HLD) + per-package low-level design (LLD)
Contributing	`/contributing/`	Contribution workflow, setup, PR process

File Naming

Use README.md for directory pages — VitePress rewrites maps them to index routes, and GitHub renders them natively
Guide pages use descriptive slugs: getting-started.md, react-vite.md, nextjs.md
Architecture LLD pages use <package>-design.md: core-design.md, store-design.md

Guide Section

The Guide section contains framework adoption guides — not core concept explanations. Core concepts belong in the API reference for @stateloom/core. Each guide walks a developer through integrating StateLoom into a specific framework or environment.

API Section

One page per package in docs/api/<package>/README.md. Covers installation, API reference, patterns, and internals.

Architecture Section

Split into two subsections:

High-Level Design: Overall design philosophy, architecture overview, layer scoping (shared across all packages)
Package Design (LLD): Per-package internals — algorithm details, data structures, scheduling strategies, design rationale

Document Structure

Package API Reference (`docs/api/<package>/README.md`) — Mandatory

Every @stateloom/* package must have comprehensive documentation in docs/api/<package>/README.md. Documentation must be created alongside code and updated whenever the code changes.

Each package page follows this structure — every section is required unless marked optional:

Title and one-line description — what this package is
Install command — with code-group for pnpm/npm/yarn
Size (gzipped) — bundle size budget
Overview diagram (Mermaid) — visual map of the package's API surface
Quick Start — minimal complete example that demonstrates the core value (< 15 lines)
Guide — step-by-step walkthrough of all features with progressive complexity
API Reference — every exported function, interface, type, and constant, each with:
- Full type signature
- Description of what it does and why you'd use it
- Parameter table (name, type, description, default)
- Return value description
- At least one code example
- Key behaviors as bullet list (equality, scheduling, cleanup, error handling)
- Links to related APIs (see also)
Patterns — common usage patterns with complete examples (derived state, async, cleanup, composition)
How It Works — explanation of internals for contributors (algorithm, data structures, scheduling)
TypeScript — type inference examples using expectTypeOf-style assertions
When to Use — decision guidance, comparison with alternatives

API Reference Entry Template

Each API entry should follow this format:

markdown

### `functionName<T>(param1: Type1, param2?: Type2): ReturnType`

One-line summary of what this function does.

**Parameters:**

| Parameter | Type                 | Description                  | Default     |
| --------- | -------------------- | ---------------------------- | ----------- |
| `param1`  | `Type1`              | What this parameter controls | —           |
| `param2`  | `Type2 \| undefined` | Optional configuration       | `undefined` |

**Returns:** `ReturnType` — description of the return value.

```typescript
import { functionName } from '@stateloom/package';

// Basic usage
const result = functionName(value);
```

**Key behaviors:**

- Behavior 1 — when and why this matters
- Behavior 2 — edge case handling
- Behavior 3 — interaction with batch/scope

**See also:** [`relatedFunction()`](#relatedfunction)

Guide Section Template

The Guide section walks through features progressively:

markdown

## Guide

### Basic Usage

Start with the simplest use case. Show what the package does in < 10 lines.

### Feature A

Explain the first concept. Code example first, then explanation.

### Feature B

Build on Feature A. Each section should be self-contained but build on prior sections.

### Advanced: Feature C

More complex patterns. Clearly label advanced topics.

Architecture Documents

Title
Overview diagram
Sections with clear scope boundaries
Decision tables (when to use what)
Mermaid diagrams for complex relationships

Framework Guide Page (`docs/guide/<framework>.md`)

Framework guide pages walk developers through integrating StateLoom into a specific framework:

Title — framework name (e.g., "React + Vite")
Description (1–2 sentences) — what this guide covers
Prerequisites — what the developer needs installed
Project Setup — scaffold command, install StateLoom packages
Basic Integration — minimal working example with the framework
Patterns — common patterns specific to this framework (hooks, composables, stores, etc.)
SSR / Build Notes — framework-specific gotchas (if applicable)
Next Steps — links to API reference and other guides

Package Design (LLD) Page (`docs/architecture/<package>-design.md`)

Per-package low-level design documents for contributors and maintainers:

Title — package name + "Design" (e.g., "Core Design")
Overview — what this document covers and why
Data Structures — key internal types, graphs, maps
Algorithm — step-by-step description of core algorithms (scheduling, diffing, etc.)
Design Decisions — rationale for key choices with alternatives considered
Mermaid Diagrams — internal data flow, state transitions
Performance Considerations — memory, CPU, GC pressure tradeoffs

Markdown Conventions

Headings

One H1 per document
Hierarchical: H2 → H3 → H4 (no skipping levels)
Headings should be descriptive, not clever

Code Blocks

Always specify language: ```typescript, ```bash, ```jsonc
Use title for file paths: ```typescript title="packages/core/src/signal.ts"
Keep examples minimal — show only what matters
Use inline code for function names, types, and package names: `signal()`, `StoreApi<T>`

Tables

Use tables for comparison and decision matrices:

markdown

| Feature      | Store    | Atom        | Proxy    |
| ------------ | -------- | ----------- | -------- |
| Mental model | Object   | Composition | Mutation |
| TypeScript   | Inferred | Inferred    | Inferred |
| Middleware   | Yes      | No          | No       |

Admonitions

VitePress supports custom containers:

markdown

::: tip
Use `batch()` to coalesce multiple signal writes into a single notification.
:::

::: warning
Calling `set()` outside a scope during SSR will trigger a development warning.
:::

::: danger
Never share a scope between requests in a serverless environment.
:::

Documentation Maintenance

When to Update Docs — MANDATORY

Documentation updates are not optional. They must accompany every code change:

Code Change	Required Doc Update
New package	Create `docs/api/<package>/README.md` with full structure
New exported function/type	Add API Reference entry + update Guide if needed
Changed behavior	Update Key behaviors, examples, and Guide sections
New pattern	Add to Patterns section
Changed types	Update TypeScript section and API signatures
Breaking change	Update migration guide, highlight in changelog
Bug fix	Update docs if the documented behavior was wrong

Review Checklist

[ ] Code examples compile and run correctly
[ ] Every exported function/type has an API Reference entry
[ ] API Reference entries have: signature, description, parameter table, return value, example, key behaviors
[ ] Guide section walks through all features progressively
[ ] Mermaid diagrams render without errors
[ ] Links are valid (no broken internal links)
[ ] Consistent terminology (use the same term for the same concept everywhere)
[ ] Package names use full scope: @stateloom/core, not core
[ ] Install commands are correct
[ ] TypeScript examples use strict mode patterns

Documentation Guidelines ​

Documentation Site Stack ​

VitePress Configuration ​

Mermaid: Browser-Side Rendering ​

Code Highlighting (Shiki) ​

Writing Style ​

Audience ​

Voice ​

Principles ​

Mermaid Diagram Standards ​

When to Use Diagrams ​

Diagram Guidelines ​

Examples ​

Site Structure ​

File Naming ​

Guide Section ​

API Section ​

Architecture Section ​

Document Structure ​

Package API Reference (docs/api/<package>/README.md) — Mandatory ​

API Reference Entry Template ​

Guide Section Template ​

Architecture Documents ​

Framework Guide Page (docs/guide/<framework>.md) ​

Package Design (LLD) Page (docs/architecture/<package>-design.md) ​

Markdown Conventions ​

Headings ​

Code Blocks ​

Tables ​

Links ​

Admonitions ​

Documentation Maintenance ​

When to Update Docs — MANDATORY ​

Review Checklist ​

Documentation Guidelines

Documentation Site Stack

VitePress Configuration

Mermaid: Browser-Side Rendering

Code Highlighting (Shiki)

Writing Style

Audience

Voice

Principles

Mermaid Diagram Standards

When to Use Diagrams

Diagram Guidelines

Examples

Site Structure

File Naming

Guide Section

API Section

Architecture Section

Document Structure

Package API Reference (`docs/api/<package>/README.md`) — Mandatory

API Reference Entry Template

Guide Section Template

Architecture Documents

Framework Guide Page (`docs/guide/<framework>.md`)

Package Design (LLD) Page (`docs/architecture/<package>-design.md`)

Markdown Conventions

Headings

Code Blocks

Tables

Links

Admonitions

Documentation Maintenance

When to Update Docs — MANDATORY

Review Checklist