| name | documentation |
| description | 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. |
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!
