octri.json

octri.json is your docs site's configuration as one JSON file. Appearance, navigation, the home page, redirects, top bar buttons, social links, SEO, page feedback, the Try it playground, custom code and custom components: everything a setting can describe is here, in one place you can read top to bottom and change in a few keystrokes.

You open it from the Files panel in API Studio, under Config.

Editing the file

Click octri.json under Config in the Files panel. It opens in the code editor in the middle of API Studio.

The file starts with a $schema line:

{
  "$schema": "https://app.octri.dev/schemas/octri.json"
}

The editor reads that schema as you type. It suggests every key that fits where your cursor is, lists the allowed values for each setting, shows what a setting does when you hover it, and underlines a mistake before you save. The schema is public, so any editor that understands JSON Schema, such as VS Code, gives you the same help if you edit a copy on your own machine. Bring that copy back with ⋯ → Import into octri.json on the Config group: its text becomes an unsaved edit in the editor, so you can read it over before you save.

Save with the Save button or Ctrl+S (Cmd+S on a Mac). Revert throws away unsaved edits.

When a save reaches readers

The label above the editor reads Draft and live, because the file holds settings that follow two different rules.

Each setting follows the same rule it follows everywhere else in the studio. Your sidebar, home page and redirects go out together in the next release, alongside your page drafts. A colour change or a new social link is on the docs site the moment you save.

How a save is read

Saving compares the file you saved with the file as it was when you opened it, and writes only the difference.

• Only what you changed is written. A setting you did not touch is never sent. If someone changes the logo in Docs settings while you edit the sidebar here, your save keeps their logo.
• Every setting is optional. Leaving one out means its default.
• Deleting a setting resets it to its default. Remove "layout": "floating" and the layout goes back to full.
• Deleting a whole section leaves it alone. If appearance, navigation or socials is missing entirely, nothing in it changes. Deleting navigation by accident cannot empty your docs site.
• Keys are strict. A misspelt key is an error, not a setting that silently does nothing.
• Nothing is written if anything is wrong. A refused save lists every problem with its place in the file, for example navigation.tabs[1].items[0].page, and you fix them and save again.

If the same settings change somewhere else while you have the file open, a notice offers Load latest. Saving anyway still writes only the parts you changed.

The shape of the file

Every section at the top level is optional.

{
  "$schema": "https://app.octri.dev/schemas/octri.json",
  "appearance": { },
  "navigation": { },
  "socials": { },
  "seo": { },
  "feedback": { },
  "playground": { },
  "customCode": { },
  "components": { }
}

customCode and components appear on the Growth plan and above. On a lower plan they are left out of the file, and adding them is refused with "Custom code is on the Growth plan and above."

appearance

How the docs site looks. Every setting here applies on save, exactly like the Appearance panel in Docs settings.

"appearance": {
  "colors": { "primary": "#FF6A00" },
  "colorScheme": "dark",
  "themeToggle": false,
  "layout": "floating",
  "contentWidth": "default",
  "corners": "default",
  "logo": {
    "light": "https://example.com/logo.svg",
    "dark": "https://example.com/logo-dark.svg",
    "link": "https://example.com",
    "show": true
  },
  "favicon": "https://example.com/favicon.png",
  "fonts": { "body": "inter", "heading": "body", "code": "jetbrains-mono" },
  "textSize": { "sidebar": "large", "content": "large", "code": "smaller" },
  "sidebar": { "style": "default", "width": "wide", "resizable": true, "lines": false, "icons": false },
  "navbar": { "layout": "default", "search": "centered", "surface": "solid" },
  "codeTheme": { "light": "octri", "dark": "octri" },
  "tableOfContents": { "endpoints": true, "pages": true },
  "repository": { "url": "https://github.com/acme/api", "stars": true }
}

Colour, scheme and layout

The four layouts:

• full: the sidebar and the On this page rail sit at the screen edges.
• contained: the whole page is one centred block.
• framed: the content sits on a raised panel.
• floating: the sidebar is a card held off the edges of the screen.

Logo and favicon

Image URLs are up to 500 characters. Upload images in Docs settings first, then copy their URLs here.

Fonts

heading: "body" uses the body face for headings. Set any slot to google and it uses the family named in the matching fonts.google field:

"fonts": {
  "body": "google",
  "code": "google",
  "google": { "body": "Source Sans 3", "code": "Source Code Pro" }
}

Text size

textSize.sidebar, textSize.content and textSize.code each take smaller, large or larger. The defaults are large for the sidebar and content, and smaller for code, so code examples sit a step below the page text.

Sidebar

Top bar

navbar.color is only read while surface is colored.

Code, rail and repository

Your custom stylesheet is not in octri.json. It is its own file, styles/custom.css, in the Files panel.

navigation

Your docs site's structure: the tabs along the top bar, the sidebar under each one, the home page, redirects and the top bar buttons.

"navigation": {
  "tabs": [
    {
      "label": "Guides",
      "type": "content",
      "path": "guides",
      "items": [
        {
          "folder": "Getting started",
          "items": ["guides/getting-started/quickstart", "guides/getting-started/authentication"]
        }
      ]
    },
    { "label": "API Reference", "type": "reference", "path": "api-reference" },
    { "label": "Changelog", "type": "changelog" },
    { "label": "Status", "type": "link", "url": "https://status.example.com" }
  ],
  "home": { "page": "guides/getting-started/quickstart" },
  "redirects": [{ "from": "/old-guides/*", "to": "/guides/*" }],
  "buttons": [{ "label": "Get an API key", "url": "https://example.com/signup", "style": "primary" }]
}

Tabs

tabs lists the top bar's tabs from left to right, up to 50. It is saved as a draft and goes live when you publish.

The four tab types:

A reference tab lists every endpoint without you naming them. Its items hold only the folders you arranged by hand; every other endpoint is listed for you. To keep an endpoint out of the reference sidebar, name it in hide:

{
  "label": "API Reference",
  "type": "reference",
  "path": "api-reference",
  "hide": ["GET /internal/health", "POST /internal/reindex"]
}

Two tabs cannot share a path, and a tab cannot take a path the docs site uses itself: api, changelog, docs, gate, no-project, not-found and theme-test. A refused path says so: "/api is used by the docs site itself. Pick another path."

Sidebar rows

A row in items takes one of five shapes. The simplest is a bare string.

"guides/getting-started/quickstart"

{
  "page": "guides/getting-started/quickstart",
  "label": "Quickstart",
  "icon": "rocket",
  "hidden": false,
  "path": "quickstart"
}

The fields a row can carry:

A folder named "" groups its rows under no heading, for rows that belong together but need no title.

Paths are read against the file as you opened it. If you move a row into another folder, keep naming the page by its old path in that save; the next time you open the file, it shows the new one.

Home page

home names the page served at the root of your docs site, /. It is saved as a draft.

"home": { "page": "guides/overview", "hideSidebar": true }

Set "home": null to have no home page.

Redirects

redirects sends readers from addresses that no longer exist to where the content lives now. Rules are checked in order, up to 500 of them, and are saved as a draft so a rename and the rule that keeps its old address working go live together.

"redirects": [
  { "from": "/getting-started", "to": "/guides/quickstart" },
  { "from": "/v1/*", "to": "/guides/*" },
  { "from": "/guides/old-page", "to": "/guides/new-page", "force": true }
]

How the rules behave:

• A live page always wins. A rule only answers for a path where nothing is published, so a redirect can never hide a working page. The exception is a force rule.
• Wildcards carry the rest of the path. With /v1/* → /guides/*, a reader at /v1/auth/keys lands on /guides/auth/keys. A to can end in /* only when its from does.
• force rules come from the page dialog. Choosing Redirect to another page in a page's dialog writes a rule with force: true that names both pages by their permanent address, so renaming either page never breaks it. A force rule cannot use wildcards.
• Octri already redirects old addresses of your own pages. When a page moves between folders, readers are sent on without a rule. Write rules for what Octri cannot guess: a page whose name changed, a section split in two, or paths from a docs site you had before Octri.

A rule is refused when:

In the editor each message starts with the rule's number, e.g. Redirect 3: Start the path with /.

Top bar buttons

buttons adds up to 3 call-to-action buttons at the right of the top bar. They apply on save.

"buttons": [
  { "label": "Dashboard", "url": "https://app.example.com", "style": "outline" },
  { "label": "Get an API key", "url": "https://app.example.com/signup", "style": "primary" }
]

Keep primary for the one action you most want readers to take.

socials

Social icons and links of your own, shown under each page. They apply on save.

"socials": {
  "github": "https://github.com/acme",
  "x": "https://x.com/acme",
  "discord": "https://discord.gg/acme",
  "custom": [
    { "label": "Community forum", "url": "https://forum.acme.com", "icon": "users" },
    { "label": "Book a demo", "url": "https://acme.com/demo", "icon": "" }
  ]
}

Each platform takes its URL: github, gitlab, x, linkedin, youtube, instagram, facebook, tiktok, reddit, discord, slack, telegram, whatsapp, twitch, mastodon, medium, devto, stackoverflow, npm, producthunt and website. Delete a platform's line to remove its icon.

custom holds up to 5 links of your own, in order. Each has a label (up to 40 characters), a url, and an icon from the docs icon set. Set icon to "" to show the label as a button instead of an icon.

seo

How your docs appear in search results and link previews. These settings apply on save.

"seo": {
  "enabled": true,
  "titleMode": "dynamic",
  "title": "Acme Docs",
  "titleTemplate": "%s · Acme Docs",
  "description": "Guides and API reference for the Acme payments API.",
  "ogImage": "https://acme.com/og.png",
  "keywords": "payments, api, sdk",
  "indexable": true,
  "twitter": "acme"
}

A page's own description is the description in its page file's frontmatter. See SEO for how titles and descriptions are put together.

feedback

"feedback": { "enabled": true }

true asks "Was this helpful?" at the bottom of every page. Votes are anonymous and show in Analytics. It applies on save and defaults to false.

playground

The Try it panel on endpoint pages, where readers send real requests to your API. These settings apply on save.

"playground": {
  "enabled": true,
  "baseUrl": "https://sandbox.acme.com/v1",
  "auth": { "type": "bearer", "headerName": "Authorization" },
  "allowedOrigins": ["https://acme.com"],
  "timeoutMs": 15000
}

auth.type and auth.headerName are saved together, so changing one writes both.

customCode

"customCode": { "enabled": true }

true loads the files in custom-code/ on every docs page: styles.css, head.html for the page's <head>, and body-end.html for the end of its <body>. false keeps those files saved but unused, which is a quick way to rule them out when something looks wrong. The code itself is edited in those files, not here. Growth plan and above; applies on save.

components

The descriptions and props of your custom components, keyed by tag. Growth plan and above; applies on save.

"components": {
  "PlanCard": {
    "description": "A pricing plan with its price and a call to action.",
    "props": [
      { "name": "title", "type": "string", "description": "The plan's name." },
      { "name": "price", "type": "number", "default": "0" },
      { "name": "featured", "type": "boolean", "default": "false" },
      { "name": "accent", "type": "color" },
      { "name": "tier", "type": "select", "options": ["free", "pro", "enterprise"], "default": "pro" },
      { "name": "children", "type": "node", "description": "What the plan includes." }
    ]
  }
}

Each prop has:

This section edits components that already exist. Create a component from ⋯ on the Components group in the Files panel, or in Docs settings; its template and stylesheet are files under components/. Naming a tag that does not exist is refused with No component "Hero". Create components in Docs settings → Components; this file edits the ones that exist. A component you leave out of the list is left as it is, never deleted.

When a save is refused

A refused save writes nothing and lists each problem with where it is in the file. The ones you are most likely to meet: