Writing documentation
Where these pages live, how to add one, the Markdown they support and the checks they pass.
On this page
These docs are Markdown files in ikazebot-web, rendered at build time by the web app itself: no CMS, no database, no separate site. A page changes in the same pull request as the feature it describes.
Where things live
| What | Where |
|---|---|
| Page text | content/docs/<section>/<slug>.md |
| The registry: sections, groups, order, titles, descriptions, related pages | src/lib/docs.ts (DOC_SECTIONS) |
| Rendering: Markdown, callouts, code blocks, diagrams | src/components/docs/ |
| Search: text extraction and ranking | src/lib/docs-search.ts; the index route is /docs/search-index |
| Links from dashboard screens | src/lib/doc-links.ts (GUIDE), passed to PageHeader as guide |
| Tests | tests/docs.test.ts, tests/docs-search.test.ts |
Every page is prerendered. The sidebar, the docs home, section pages, previous and next, the sitemap and search all read DOC_SECTIONS, so a page exists once it has an entry there and a file.
Add a page
- Write
content/docs/<section>/<slug>.md. No#heading: the layout draws the title and description from the registry. Start with a sentence that says what the feature does. - Add
{ slug, title, description }to the right group inDOC_SECTIONS. The description is one sentence; it is the page's meta description and its line in every listing. - Optionally add
related: [...]: slugs in the same section that are genuinely worth reading next. Leave it out rather than pad it. - If a dashboard screen explains itself with this page, add an entry to
GUIDEand pass it to that screen'sPageHeader. - Run
pnpm test. It fails on an unregistered file, a registered page with no file, or any broken link or anchor.
A slug is permanent once published: other pages, the dashboard and search engines link to it.
Write only what is shipped
The docs describe what a workspace can do today. Before writing a sentence, check it against the code: the screen's labels, the shared schemas in src/lib/shared, the error codes, the plan config. Not planned work, not the roadmap.
- Never invent an endpoint, field, limit, screen or behaviour. If you cannot point at the code that does it, do not write it.
- Plan limits and prices are not repeated. Link to
/pricing, which reads them fromPLANS, so the docs cannot disagree with a workspace. - When a feature changes, its page changes in the same pull request. When a feature ships, add it to Release notes (
guide/release-notes.md) under the date it was completed. - Use the names on the screen, in bold: Settings → Members, Save widget settings.
Markdown you can use
GitHub-flavoured Markdown: headings, lists, tables, links, inline code and fenced code. Raw HTML is ignored.
Headings and anchors
Use ## for sections and ### under them; both appear in On this page and get an anchor made from their text: ## Add a website becomes #add-a-website. Two headings on one page must not make the same anchor. Renaming a heading breaks links to it; the tests will tell you which.
Links
Link to other pages with absolute paths: [Knowledge](/docs/guide/knowledge), or to a section with /docs/guide/knowledge#add-a-website. Links to app pages such as /pricing are checked against the routes in src/app. External links open in a new tab.
Callouts
GitHub's alert syntax. Use them sparingly, for what a reader must not miss:
> [!WARNING]
> Deleting a workspace cannot be undone.
The kinds are NOTE, TIP, IMPORTANT, WARNING and CAUTION. A plain > quote renders as a neutral note.
Code
Fence code with its language (```bash, ```json, ```js). Every code block gets a Copy button that copies exactly the source. Use placeholders that cannot be mistaken for real values: ikb_your_key, AGENT_ID.
Step diagrams
A code block fenced as flow draws a step diagram from one step per line, with an optional caption after |:
```flow
Visitor writes | in the widget
Knowledge is searched
The model answers
```
Search and indexing
Search covers every page's title, description, headings and text, including code. Nothing to configure: a new page is in the index on the next build. The dialog opens with Ctrl K (⌘K on a Mac) or /; /docs/search?q= is the same search without JavaScript.
The user guide is indexed by search engines and listed in sitemap.xml. The developer guide is readable but marked noindex (indexed: false on its section in DOC_SECTIONS). Canonical URLs and the sitemap need SITE_URL set at build time; without it they are left out rather than guessed.
Before you merge
pnpm typecheck && pnpm lint && pnpm test
pnpm test checks the registry against content/docs, every internal link and anchor, the dashboard's GUIDE links and their titles, the callout kinds, search behaviour, and that no docs code reads a session. Then open the page with pnpm dev, in light and dark, at phone width.