Appearance

Appearance controls how your docs site looks: colours, the logo, fonts, layout, the top bar and the sidebar. Open Docs settings in API Studio and choose Appearance. The preview beside the settings is the docs page itself, with a switch to check it in light and dark.

Changes apply as soon as you save them, without a publish. Reset to defaults puts every setting back to the defaults below.

Each setting below names its key in octri.json, under appearance, and the key octri docs theme set takes.

Brand

Primary colorcolourdefault: #ff6a00

Links, active sidebar rows and primary buttons. Any colour works: links use a shade of it adjusted for each scheme, so they stay readable on white and on dark.

colors.primary · CLI primaryColor

Logoimagedefault: none

The image in the top bar, uploaded separately for light and dark. The dark one falls back to the light one. Up to 500 characters of URL.

logo.light, logo.dark · CLI logoUrl, logoUrlDark

Logo linkpath or URLdefault: the docs home

Where clicking the logo goes, such as your marketing site.

logo.link · CLI logoHref

Show logoon or offdefault: on

Off draws your project's name and initial instead, and keeps the images for when you turn it back on.

logo.show · CLI showLogo

Faviconimagedefault: none

The icon in the browser tab. An SVG or WebP favicon also gets a PNG copy, because Google's search results can't show those two formats.

favicon · CLI faviconUrl

Light and dark

Color schemechoicedefault: system

The scheme a reader starts in.

Value	Meaning
`system`	Follows the reader's operating system
`light`	Always starts light
`dark`	Always starts dark

colorScheme · CLI colorScheme

Light and dark switchon or offdefault: on

The switch in the top bar that lets readers change scheme. It stays available with any starting scheme.

themeToggle · CLI showThemeToggle

Layout

Page layoutchoicedefault: full

How the page is framed.

Value	Studio label	Meaning
`full`	Full width	The sidebar and the On this page rail at the screen edges
`contained`	Contained	The whole page as one centred block
`framed`	Framed	The content on a raised panel
`floating`	Floating	The sidebar as a card held off the edges

layout · CLI layout

Content widthchoicedefault: default, 1040px

The width of the reading column.

Value	Width
`narrow`	800px
`default`	1040px
`wide`	1280px

contentWidth · CLI contentWidth

Border radiuschoicedefault: default, slightly rounded

How rounded corners are, across the whole site: cards, code panels, buttons and badges.

Value	Meaning
`sharp`	Square corners
`default`	Slightly rounded
`rounded`	Rounder, and buttons and badges become pills

corners · CLI borderRadius

Fonts

Font familychoicedefault: manrope

The face for body text: manrope, inter, plus-jakarta-sans, dm-sans, system (the reader's own interface font) or google.

fonts.body · CLI fontFamily

Heading fontchoicedefault: body

The face for headings. body uses the body face, shown as Match body. Otherwise manrope, inter, plus-jakarta-sans, dm-sans or google.

fonts.heading · CLI headingFont

Code fontchoicedefault: jetbrains-mono

The face for code: jetbrains-mono, fira-code, ibm-plex-mono, system or google.

fonts.code · CLI codeFont

Google fontfamily namedefault: none

Any Google Fonts family, such as Source Sans 3, used by a slot set to google. Each slot has its own. A slot set to google with no family named falls back to the default face.

fonts.google.body, fonts.google.heading, fonts.google.code · CLI googleFontFamily, googleHeadingFont, googleCodeFont

Top bar

Layoutchoicedefault: default, one row

Value	Studio label	Meaning
`default`	One row	Logo, tabs and actions on one row
`stacked`	Tabs below	Tabs on a second row
`centered`	Centered tabs	Tabs in the middle of the row

navbar.layout · CLI navbarLayout

Searchchoicedefault: sidebar

Where search sits.

Value	Studio label	Meaning
`sidebar`	In the sidebar	At the top of the sidebar, above the pages
`centered`	Centered	A field in the middle of the top bar
`button`	Search button	A button that opens into a field

On a page that hides its sidebar, such as a home page, sidebar leaves no search on a wide screen, so centered or button suits a site with one.

navbar.search · CLI searchPlacement

Top bar backgroundchoicedefault: frosted

What the bar is made of.

Value	Meaning
`solid`	Opaque
`frosted`	Glass: the page blurs behind it as you scroll
`transparent`	Barely there
`colored`	Filled with the Top bar color

navbar.surface · CLI navbarSurface

Top bar colorcolourdefault: the primary colour

The fill when the background is colored, set separately for light and dark. Ignored for any other background.

navbar.color.light, navbar.color.dark · CLI navbarColor, navbarColorDark

RepositoryURLdefault: none

Links your source repository from the top bar. Stars shows its star count beside the link.

repository.url, repository.stars · CLI repoUrl, repoStarsEnabled

Call-to-action buttons and social links are set under navigation.

Stylechoicedefault: default rows

How rows are drawn: default, bordered or minimal. The preview shows each one.

sidebar.style · CLI sidebarStyle

Widthchoicedefault: default, 280px

The starting width.

Value	Width
`compact`	240px
`default`	280px
`wide`	340px

sidebar.width · CLI sidebarWidth

Let readers resize iton or offdefault: on

Readers can drag the sidebar's edge wider or narrower.

sidebar.resizable · CLI sidebarResizable

Folder lineson or offdefault: off

Draws a line down each folder's children.

sidebar.lines · CLI showSidebarLines

Iconson or offdefault: on

Shows folder, page and link icons beside each row.

sidebar.icons · CLI showSidebarIcons

Code and page outline

Light themechoicedefault: octri

Code highlighting in the light scheme: octri, github, monokai, nord or dracula.

codeTheme.light · CLI codeTheme

Dark themechoicedefault: octri

Code highlighting in the dark scheme, from the same list.

codeTheme.dark · CLI codeThemeDark

On this pageon or offdefault: off for endpoints, on for pages

The outline at the right of a page, set separately for endpoint pages and written pages.

tableOfContents.endpoints, tableOfContents.pages · CLI showToc, showGuideToc

Examples

A dark site in your colour, with search in the middle of the top bar:

"appearance": {
  "colors": { "primary": "#0e7c66" },
  "colorScheme": "dark",
  "navbar": { "search": "centered", "surface": "solid" },
  "sidebar": { "width": "wide", "lines": true }
}

The same from a terminal:

octri docs theme set primaryColor=#0e7c66 colorScheme=dark searchPlacement=centered navbarSurface=solid sidebarWidth=wide showSidebarLines=true

Going further

For what the settings don't cover, write your own CSS with custom code. The site's name and the "Powered by Octri" mark are under white label.

Navigation: tabs, nav buttons and social links.
octri.json: every setting as text.
octri docs theme: the same settings from a terminal.