Documentation conventions and where to look. Read the actual website/ tree and config to confirm details, since pages and versions change over time.
1. Framework & Config
- Docusaurus 3.x at
website/. For the exact version, read website/package.json
- Config:
website/docusaurus.config.ts. Sidebar: website/sidebars.ts (top-level items are manual, the docs/tutorials/examples categories are autogenerated from their directories)
- Versioning: the
current docs are the active version, older majors are kept but marked unmaintained. Read the versions block in website/docusaurus.config.ts and website/versions.json for the live set of versions and their labels
2. Language Policy
- English is mandatory. Use i18n (
website/i18n/) only on explicit user request
3. Documentation Structure
The docs live under website/docs/:
- Root pages cover the homepage, philosophy, and the comparison with other runners
documentation/ is the API reference, organized by area: assertions, helper APIs (under helpers/), and the poku runner with its CLI options (under poku/)tutorials/ holds guided walkthroughs and examples/ holds runnable examples
Read the website/docs/ tree to discover the current pages rather than relying on a fixed list here, since pages are added and reorganized.
4. Feature-to-Docs Mapping
There is a close (not strictly 1:1) mapping between helper APIs in src/modules/helpers/ and pages under website/docs/documentation/helpers/. Conventions to expect:
- Most helpers have a matching page of the same name
- Related helpers are sometimes grouped into a subdirectory (for example, process-related helpers)
- A single source helper can be split across multiple pages, and a single page can cover more than one export
- The config option types inform the
poku/options/ pages
- The public surface is whatever
package.json exports define, not the internal file layout
To find the doc for a feature, read the helpers directory and the docs directory and match by responsibility, rather than trusting a fixed table.
5. Documentation Conventions
When reading or writing docs, follow these patterns:
- Front matter: YAML with
sidebar_position and tags
- Page structure: function signature (
> fn(params)) then Basic Usage then Advanced then FAQ
- Components: reusable MDX components live in
website/src/components/ (for example FAQ, and History to document when a feature became available or had breaking changes across versions). Docusaurus components like Tabs/TabItem are also available
- Category organization:
_category_.json files
- Punctuation: Use proper punctuation. Never use any kind of substitute as a crutch
- Consistency: Match the writing style, tone, and structure of the related existing docs
6. Inline Documentation (JSDoc)
- Type definitions live in
src/@types/
- Pattern: description plus an
@default tag
- These inform the documentation content
7. LLM Docs (Context7)
website/llms/ holds docs written for LLMs and indexed by Context7, separate from the human-facing pages in website/docs/- Current files:
llms.md (the llms.txt entry point, symlinked to website/static/llms.txt), comparing.md, and philosophy.md
context7.json at the repo root controls what Context7 indexes and how it guides the agent through the folders allowlist (which includes website/llms), the description, and the rules- The
description and rules have Context7 length limits, validated by test/unit/context7-rules.test.ts
8. Changelog
CHANGELOG.md is auto-generated: NEVER edit it!
1---2name: documentation3description: Documentation deep-dive for the poku website covering Docusaurus setup, language policy, feature-to-docs mapping, conventions, JSDoc, and the changelog. Use when editing or adding docs or mapping a feature to its page.4---56Documentation conventions and where to look. Read the actual `website/` tree and config to confirm details, since pages and versions change over time.78### 1. Framework & Config910- Docusaurus 3.x at `website/`. For the exact version, read `website/package.json`11- Config: `website/docusaurus.config.ts`. Sidebar: `website/sidebars.ts` (top-level items are manual, the docs/tutorials/examples categories are autogenerated from their directories)12- Versioning: the `current` docs are the active version, older majors are kept but marked unmaintained. Read the `versions` block in `website/docusaurus.config.ts` and `website/versions.json` for the live set of versions and their labels1314### 2. Language Policy1516- English is mandatory. Use i18n (`website/i18n/`) only on explicit user request1718### 3. Documentation Structure1920The docs live under `website/docs/`:2122- Root pages cover the homepage, philosophy, and the comparison with other runners23- `documentation/` is the API reference, organized by area: assertions, helper APIs (under `helpers/`), and the `poku` runner with its CLI options (under `poku/`)24- `tutorials/` holds guided walkthroughs and `examples/` holds runnable examples2526Read the `website/docs/` tree to discover the current pages rather than relying on a fixed list here, since pages are added and reorganized.2728### 4. Feature-to-Docs Mapping2930There is a close (not strictly 1:1) mapping between helper APIs in `src/modules/helpers/` and pages under `website/docs/documentation/helpers/`. Conventions to expect:3132- Most helpers have a matching page of the same name33- Related helpers are sometimes grouped into a subdirectory (for example, process-related helpers)34- A single source helper can be split across multiple pages, and a single page can cover more than one export35- The config option types inform the `poku/options/` pages36- The public surface is whatever `package.json` `exports` define, not the internal file layout3738To find the doc for a feature, read the helpers directory and the docs directory and match by responsibility, rather than trusting a fixed table.3940### 5. Documentation Conventions4142When reading or writing docs, follow these patterns:4344- **Front matter**: YAML with `sidebar_position` and `tags`45- **Page structure**: function signature (`> fn(params)`) then Basic Usage then Advanced then FAQ46- **Components**: reusable MDX components live in `website/src/components/` (for example `FAQ`, and `History` to document when a feature became available or had breaking changes across versions). Docusaurus components like `Tabs`/`TabItem` are also available47- **Category organization**: `_category_.json` files48- **Punctuation**: Use proper punctuation. Never use any kind of substitute as a crutch49- **Consistency**: Match the writing style, tone, and structure of the related existing docs5051### 6. Inline Documentation (JSDoc)5253- Type definitions live in `src/@types/`54- Pattern: description plus an `@default` tag55- These inform the documentation content5657### 7. LLM Docs (Context7)5859- `website/llms/` holds docs written for LLMs and indexed by Context7, separate from the human-facing pages in `website/docs/`60- Current files: `llms.md` (the llms.txt entry point, symlinked to `website/static/llms.txt`), `comparing.md`, and `philosophy.md`61- `context7.json` at the repo root controls what Context7 indexes and how it guides the agent through the `folders` allowlist (which includes `website/llms`), the `description`, and the `rules`62- The `description` and `rules` have Context7 length limits, validated by `test/unit/context7-rules.test.ts`6364### 8. Changelog6566- `CHANGELOG.md` is auto-generated: **NEVER** edit it!
wellwelwel