Add pages and sections
Create pages, group them into sections and control the order.
0:00 / 0:19
Create a file
Put pages in folders to build the URL. The folder is a route segment, not a sidebar section.
docs/guides/webhooks.md --- title: Receiving webhooks sidebarTitle: Webhooks description: Verify and handle inbox events. --- ## Verify the signature Reject any delivery without a valid signature.Add it to navigation
Navigation is configured independently of the filesystem. Reference pages by slug.
specistry.config.ts navigation: [ "quickstart", { section: "Guides", items: [ "guides/webhooks", { page: "guides/ci", label: "CI" }, ] }, { api: true, label: "API reference" }, { label: "Status", link: "https://status.acme.dev" }, ],Validate
Every navigation problem is reported against the config path, for example
config#/navigation/1/items/0.terminal npx specistry validate
Navigation nodes
| Node | Meaning |
|---|---|
"slug" | A page; label is sidebarTitle or title |
{ page, label? } | A page with an explicit label |
{ section, items } | A titled group — at most two levels deep |
{ api: true, label? } | The generated API reference, at most once |
{ label, link } | An external https:// or http:// link |
Edge cases
Page listed but file missing
NAVIGATION_PAGE_MISSING✕ FAILSspecistry.config.ts
{ section: "Guides", items: ["guides/webhook"] }✓ FIXspecistry.config.ts
{ section: "Guides", items: ["guides/webhooks"] }The slug does not match a file (note the missing s).
Sections nested three deep
NAVIGATION_DEPTH_EXCEEDED✕ FAILSspecistry.config.ts
{ section: "A", items: [{ section: "B", items: [
{ section: "C", items: ["x"] } ] }] }✓ FIXspecistry.config.ts
{ section: "A", items: [{ section: "B · C", items: ["x"] }] }Sections nest at most two levels.
Two API entries
NAVIGATION_API_DUPLICATE✕ FAILSspecistry.config.ts
{ api: true, label: "Reference" },
{ api: true, label: "Endpoints" },✓ FIXspecistry.config.ts
{ api: true, label: "API reference" },The API reference appears in one place.
A page you forgot to list
NAVIGATION_PAGE_ORPHANED · warning✕ FAILSdocs/
docs/guides/retries.md # not in navigation✓ FIXspecistry.config.ts
{ section: "Guides", items: ["guides/webhooks", "guides/retries"] }Still reachable by URL, but not in the sidebar. Fine for hidden pages.