Wiki authoring

How to write and maintain pages in this WitWiki instance — for humans in the web UI and for agents via MCP.

  • Internal links: [[path]] or [[path|label]] (e.g. [[about/architecture]]).
  • Paths are lowercase, often nested (about/development).
  • The server records outbound links for wiki_lint (orphans and dead targets).

Diagrams (Mermaid)

Use a Markdown code fence with the mermaid language tag. The Next.js wiki viewer renders them as SVG.

Example:


flowchart LR
  A[Agent] --> B[Go API]
  B --> C[(Postgres)]

Larger diagrams: prefer separate charts (or stacked subgraphs) so Mermaid does not squeeze two panels side by side. Optional first line:

%%{init: {'flowchart': {'nodeSpacing': 44, 'rankSpacing': 52}, 'themeVariables': {'fontSize': '16px'}}}%%

See architecture for a production example.

Lint caveats

wiki_lint treats [[...]] in page bodies as links. Pages that document wikilink syntax (or show examples in prose) can produce false dead-link hits. Prefer rephrasing examples or accept noise until the linter ignores code spans.

Repo seed vs live wiki

  • make seed (from the host, with Compose) upserts pages listed in api/cmd/server/seed.go — including the index and starter about/* content.
  • Agents usually edit live pages via MCP; those changes are not written back to seed.go unless someone copies them into the repo.
  • After changing seed content, run make seed to refresh the database.

Docker: web node_modules

Compose bind-mounts ./web but keeps /app/node_modules in an anonymous volume. If you add an npm package (e.g. mermaid), run make web-install once so that volume is updated; then restart web if needed.

← development · mcp-tools