Wanaku

Appearance

Write Wanaku Semantic Router documentation ​

This page describes the shape of a Wanaku Semantic Router (WSR) documentation page and the checks that CI runs on the docs/ tree. These rules are the same as in the Wanaku documentation conventions. Use ASD-STE100 Simplified Technical English for technical content, and plain technical English for introductions and framing text.

Sections ​

The docs/ tree has one folder for each reader task:

FolderReader task
get-started/Learn how WSR works and run a first route.
operate/Run the runtime and the preview service in a deployment.
reference/Look up the command line, configuration, contracts, and APIs.
contributing/Build, test, and release WSR.

Each folder has an index.md hub. The hub lists every page in its folder. Keep a hub at 70 lines or fewer.

Files and slugs ​

  • Use lowercase kebab-case file names with four words or fewer. The folder supplies the group name: use operate/kubernetes.md, not operate/operate-kubernetes.md.
  • Use a verb-object slug for a tutorial or a how-to, for example run-a-published-route.md. Use a noun for a reference or a concept page, for example preview-api.md.
  • Do not put version numbers or a -guide suffix in new slugs.
  • A slug is a published URL. When you move or rename a page, add a line to docs/redirects.txt in the same pull request. Each line has the old slug and the new slug.

Frontmatter ​

Each page starts with a title and a description:

markdown
---
title: Run a published semantic route
description: Start the Wanaku Semantic Router runtime from a route that Barn publishes, pin an explicit catalog revision and digest, and stop the runtime safely.
---
  • title has 60 characters or fewer and is unique. Do not add a " | Wanaku Semantic Router" suffix. The site adds it.
  • description has 120 to 155 characters and is unique. Write it in short, active sentences.
  • If a value contains a colon followed by a space, put the value in double quotes. Otherwise, the frontmatter is not valid YAML.

Page skeleton ​

markdown
# H1 with the same meaning as the title

One to three sentences: what the reader can do after this page.

## Prerequisites (omit when empty)

## Body sections (specific H2s, never "Overview")

## Next steps (two to four links, nothing after this section)

Use one page type for each page:

TypeH1Body
Tutorial"Run a route from local files"Numbered steps with one visible result.
How-toVerb first: "Deploy on Kubernetes and OpenShift"Goal, steps, and verification.
ReferenceNoun: "Semantic evaluation preview API"Tables and schemas, in alphabetical or schema order.
Explanation"How Wanaku Semantic Router works"The model, a diagram, and the limits.
Troubleshooting"Troubleshoot Wanaku Semantic Router"The symptom or the exact error as the heading, then the cause and the fix.

Keep tutorials and how-tos at 350 lines or fewer, explanations at 500, and references at 800. Split a longer page by task.

  • Use relative links with the .md extension, for example ../reference/configuration.md.
  • Do not leave docs/ with a relative link. The site publishes only the docs/ tree. Link code, configuration, and example files with https://github.com/wanaku-ai/wanaku-semantic-router/blob/main/<path>.
  • Link fragments only to H2 and H3 headings.
  • Use the name of the destination page as the link text. Do not use "here".
  • End each page with one "Next steps" section. Do not use "Related Docs".
  • Add each page to docs/nav.json exactly once. The website builds the sidebar from this file.

Headings and callouts ​

  • Use one H1. Do not skip heading levels. Stop at H3.
  • Use sentence case for new and renamed headings. Do not rename headings in a move-only change, because that breaks anchors.
  • Do not number headings. Renumbering breaks anchors.
  • Expand acronyms on first use in an H1 or a description, for example WSR (Wanaku Semantic Router) and MCP (Model Context Protocol).
  • Use GitHub alert syntax for callouts: > [!NOTE], > [!IMPORTANT], and > [!WARNING].
  • Do not write a "Contents" list. GitHub and the site show an outline.

Images ​

  • Put images in docs/imgs/ with the name <page-slug>-<what>.png.
  • Add alt text to each image. Use PNG or WebP, 200 KB or less, and 1280 px wide or less.
  • Use code blocks, not screenshots, for text.

Check your changes ​

CI runs these checks on each pull request that changes Markdown or the docs navigation. Run them locally before you push:

bash
python3 .github/check-docs-nav.py
npx markdownlint-cli2
lychee --offline --include-fragments --exclude-path target '**/*.md'

.github/check-docs-nav.py checks the rules on this page:

  • Each page is in docs/nav.json exactly once, and each nav.json link has a page.
  • Each page is linked from its folder hub.
  • Each page has a title and a description of the correct length, and no other page has the same values.
  • No relative link leaves docs/.
  • No page has a "Related Docs" heading.
  • No page uses a bold callout such as > **Note:**. Use GitHub alert syntax.
  • Each docs/redirects.txt target has a page.

Next steps ​