DocoraDocora

Core Concepts

Configuration

Every option the theme reads, and what it controls.

defineDocsConfig is an identity function that types the object. Pass the result to DocsRoot.

// docs.config.ts
import { defineDocsConfig } from 'docora'
 
export default defineDocsConfig({
  site: { name: 'Acme', description: 'Acme documentation' },
})

site

name is the fallback header title and locale becomes <html lang>. description and url feed the metadata work in Phase 4.

header

title overrides site.name. logo.light and logo.dark swap with the colour mode. links are the top-level links beside the logo. Set search: false to drop the search trigger.

navigation

The sidebar tree. A node with children and no href is a section heading; a node with an href is a link.

navigation: [
  {
    label: 'Getting started',
    children: [{ label: 'Installation', href: '/docs/getting-started' }],
  },
]

socials

A map of network to profile URL. github, x, discord, linkedin, youtube and bluesky get brand marks; anything else falls back to a generic link icon.

toc

title renames the heading list, enabled: false removes it, and bottom.links adds a community block underneath.

github

url, branch and rootDir describe the repository. The "edit this page" links that use them arrive in Phase 8.

footer

credits sit on the copyright row. links is a flat list; columns groups links under headings. Omit all three and the footer does not render.

footer: {
  credits: 'Built with Docora',
  columns: [
    {
      title: 'Docs',
      links: [{ label: 'Introduction', href: '/docs/getting-started/introduction' }],
    },
  ],
}

colorMode

default picks the initial mode for a visitor with no stored preference. forced pins the site to light or dark and hides the toggle.

Palette and typography

Colours, radius and the font are CSS variables, not config keys. The defaults are a zinc ramp with an emerald primary and Public Sans. Redefine any token after @import 'docora/styles.css' — see Theme.

Icons

icon on a navigation item or TOC link takes a lucide name in kebab-case:

navigation: [
  {
    label: 'Getting Started',
    icon: 'rocket',
    children: [{ label: 'Introduction', href: '/docs', icon: 'house' }],
  },
]

Around thirty common documentation icons are bundled and render on the server; any other name is loaded lazily on the client.

search

The palette is on by default. With an empty query it lists the top-level documentation groups and colour-mode commands. enabled: false removes it and its trigger, and endpoint points at a different route if you serve the index elsewhere.

search: { enabled: true, endpoint: '/api/search' }

seo

title overrides site.name in the title template, titleTemplate changes its shape, and ogImage points at a different image route.

Canonical links, sitemap entries and social images need site.url. Without it they are left out rather than emitted as relative URLs.

loadingIndicator

The progress bar across the top of the page during navigation. It is on by default; enabled: false removes it.

loadingIndicator: {
  color: 'var(--primary)',
  height: 3,
}

It starts on a click that will actually navigate — hash links, external links, downloads and modifier-clicks are ignored — and completes when the pathname changes. A 200ms throttle means instant navigations never flash it.