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, readwebsite/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
currentdocs are the active version, older majors are kept but marked unmaintained. Read theversionsblock inwebsite/docusaurus.config.tsandwebsite/versions.jsonfor 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 (underhelpers/), and thepokurunner with its CLI options (underpoku/)tutorials/holds guided walkthroughs andexamples/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.jsonexportsdefine, 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_positionandtags - Page structure: function signature (
> fn(params)) then Basic Usage then Advanced then FAQ - Components: reusable MDX components live in
website/src/components/(for exampleFAQ, andHistoryto document when a feature became available or had breaking changes across versions). Docusaurus components likeTabs/TabItemare also available - Category organization:
_category_.jsonfiles
6. Inline Documentation (JSDoc)
- Type definitions live in
src/@types/ - Pattern: description plus an
@defaulttag - These inform the documentation content
7. Changelog
CHANGELOG.mdis auto-generated. NEVER edit it.
Source: wellwelwel/poku — distributed by TomeVault.