Navigation
The sidebar is built for you and stays correct as your API grows. You can also take control of it when the automatic order isn't the story you want to tell.
The default
With no custom navigation, the sidebar is derived automatically:
- Guides first
Your guide groups, in the order you set, above everything else.
- Then endpoints
Grouped by the first segment of their URL path, sorted by path and then by method.
This needs no maintenance: a newly ingested endpoint appears on its own.
Custom navigation
The nav editor lets you reorder sections, rename items, hide them, and weave guides in among endpoints.
A hidden item disappears from the sidebar but stays reachable at its URL. To make a page genuinely private, unpublish it or use access control.
Tabs
For larger sites, a tabbed layout splits the docs into independent top-level sections, each with its own sidebar.
| Tab kind | Behaviour |
|---|---|
reference | The API reference. While visible, auto-appends every endpoint you don't explicitly place |
content | A curated tab. You choose what goes in |
link | An external link in the top nav, with no sidebar |
changelog | Your release feed at /changelog. A nav position with no sidebar of its own, shown once the project has entries |
The reference and changelog tabs are permanent: you can reorder and hide them, but not rename or delete them. Hiding is how you take either one off the public nav.
Endpoints you don't place land in the reference tab; guides you don't place land in the first visible tab with a sidebar. So you can adopt a custom nav gradually instead of all at once.
Only visible tabs collect what the IA doesn't place, and nothing re-homes the endpoints the reference tab was carrying. Hide it and they leave the sidebar altogether while staying reachable at their URLs. Place the ones you want kept in another tab first, or leave the reference tab visible and hide it per route.
Page addresses
A tab's sidebar decides its pages' URLs, one segment per folder:
| Row | Address |
|---|---|
| Loose in a tab | /<tab>/ |
| In a folder | /<tab>/ |
| In a nested folder | /<tab>/ |
Each segment follows the name by default, and you can set your own under URL path. Two rows in one folder can't share a name.
Older addresses redirect to the current one. For a page whose name changed, keep the old address working, and for everything else, add a redirect rule.
Folders
| Option | What it does |
|---|---|
| Icon | A glyph before the name. Leave it for the folder mark, or choose none |
| Badge | A short word after the name, up to 24 characters, such as New |
| Badge color | Accent, gray, green, blue, amber, red or purple |
| Linked page | A page that the folder's name opens |
| Collapsible | Off draws a fixed, always-open heading in a heavier weight |
| Hidden | Keeps it out of the published sidebar, with everything inside, while you assemble it |
| URL path | The folder's segment in its pages' addresses |
Rows
Each row in a folder is one of these:
| Row | What it is |
|---|---|
| Page | A page you wrote. See writing guides |
| Endpoint | An endpoint from your spec. See editing endpoints |
| Link | Goes to another site, or a path on this one |
| Folder | Holds more rows |
A row can have its own label, so a long page title can read shorter in the sidebar. Labels and URL paths belong to the placement, so one page can read differently in two tabs.
Nav buttons
Up to three call-to-action buttons at the right of the top bar, set under CTA buttons, left to right. They apply as soon as you save, without a publish. In octri.json they're the buttons list, and octri docs buttons adds and removes them.
LabeltextrequiredThe button's text, up to 40 characters.
label
URLlinkrequiredAn http or https URL, a mailto: address, or a path on your site starting with /.
url
Stylechoiceplain (text), outline (an outlined button) or primary (filled in your brand colour). Keep primary for the one action you most want readers to take.
style
Social links
Links shown under each page, set under Socials. They apply as soon as you save. In octri.json they're socials, and octri docs socials sets them.
PlatformsURL eachOne link per platform, drawn as its icon:
| Platform | Key |
|---|---|
| GitHub, GitLab | github, gitlab |
| X, LinkedIn, Mastodon | x, linkedin, mastodon |
| YouTube, Twitch, TikTok, Instagram, Facebook | youtube, twitch, tiktok, instagram, facebook |
| Discord, Slack, Telegram, WhatsApp, Reddit | discord, slack, telegram, whatsapp, reddit |
| Medium, DEV, Stack Overflow | medium, devto, stackoverflow |
| npm, Product Hunt | npm, producthunt |
| Your website | website |
An empty link removes that platform's icon.
Custom linkslistUp to five links of your own, in order, each with a label of up to 40 characters, a URL and an icon. With no icon, the label shows as a button instead.
custom
The same thing as a file
Everything on this page is also navigation in octri.json:
{
"navigation": {
"tabs": [
{
"label": "Guides",
"type": "content",
"path": "guides",
"items": [
{
"folder": "Get started",
"icon": "rocket",
"items": ["quickstart", { "page": "authentication", "label": "Auth" }]
}
]
},
{ "label": "API Reference", "type": "reference" },
{ "label": "Changelog", "type": "changelog" }
],
"buttons": [{ "label": "Sign up", "url": "https://acme.com/signup", "style": "primary" }]
}
}Ordering
Groups and the guides inside them each carry an explicit order. Endpoints inherit their order from the spec's paths.
The most useful first page is rarely the one that sorts first. Put the overview at the top and the reference material at the bottom, whatever their names.
Versioned navigation
Version-scoped navigation is derived automatically, because endpoints differ between versions. Guides are not version-scoped, so they stay pinned across all of them. See Versioning.
From the CLI
Navigation, the home page and redirects can be drafted and published with octri docs nav.