Skip to content

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

WhatWhere
Page textcontent/docs/<section>/<slug>.md
The registry: sections, groups, order, titles, descriptions, related pagessrc/lib/docs.ts (DOC_SECTIONS)
Rendering: Markdown, callouts, code blocks, diagramssrc/components/docs/
Search: text extraction and rankingsrc/lib/docs-search.ts; the index route is /docs/search-index
Links from dashboard screenssrc/lib/doc-links.ts (GUIDE), passed to PageHeader as guide
Teststests/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

  1. 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.
  2. Add { slug, title, description } to the right group in DOC_SECTIONS. The description is one sentence; it is the page's meta description and its line in every listing.
  3. Optionally add related: [...]: slugs in the same section that are genuinely worth reading next. Leave it out rather than pad it.
  4. If a dashboard screen explains itself with this page, add an entry to GUIDE and pass it to that screen's PageHeader.
  5. 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 from PLANS, 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.

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:

md
> [!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

bash
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.

Get started free — 50 credits a month