Theme Config
Full reference for the themeConfig section of docusaurus.config.ts. These options control site metadata, navigation, footer, color mode, and content display.
Top-Level Structure
themeConfig: {
site: { /* ... */ },
colorMode: { /* ... */ },
navbar: { /* ... */ },
docs: { /* ... */ },
blog: { /* ... */ },
tableOfContents: { /* ... */ },
announcementBar: { /* ... */ },
backToTopButton: true,
errorPages: { /* ... */ },
footer: { /* ... */ },
},
Site
| Option | Type | Default | Description |
|---|---|---|---|
site.logo | object | {} | Logo configuration. |
site.logo.alt | string | undefined | undefined | Logo alt text. |
site.logo.src | object | {} | Logo icon image source paths (light/dark variants). |
site.logo.src.light | string | undefined | undefined | Light mode logo icon source path. |
site.logo.src.dark | string | undefined | undefined | Dark mode logo icon source path. |
site.logo.href | string | undefined | undefined | Logo click URL. |
site.logo.target | string | undefined | undefined | Logo link target attribute (e.g. '_blank'). |
site.logo.rel | string | undefined | undefined | Logo link rel attribute (e.g. 'noopener'). |
site.logo.ariaLabel | string | undefined | undefined | Logo link accessible label. |
site.logo.wordmark | object | {} | Wordmark image source paths (full logo with text). |
site.logo.wordmark.light | string | undefined | undefined | Light mode wordmark image source path. |
site.logo.wordmark.dark | string | undefined | undefined | Dark mode wordmark image source path. |
site.image | string | '' | Default social/SEO image path. |
site.metadata | Array<{ name: string, content: string }> | [] | Additional meta tags. |
Brand title
The navbar brand text is your site's top-level title (set in docusaurus.config.ts). For a custom brand that differs from the site title, supply a wordmark image (site.logo.wordmark) — it replaces the text.
Color Mode
| Option | Type | Default | Description |
|---|---|---|---|
colorMode.defaultMode | 'system' | 'light' | 'dark' | 'system' | Default color mode on first visit. |
colorMode.disableSwitch | boolean | false | Hide the color mode toggle. Setting defaultMode to 'system' already respects OS preference. |
Navbar
| Option | Type | Default | Description |
|---|---|---|---|
navbar.hideOnScroll | boolean | false | Hide the navbar when scrolling down. |
navbar.items | NavbarItem[] | [] | Navigation items. See below. |
Navbar Items
Each item in the navbar.items array follows this structure:
| Property | Type | Description |
|---|---|---|
label | string | Display text. |
position | 'left' | 'right' | Side of the navbar. |
type | string | undefined | Docusaurus navbar item kind (see note). Omit for a plain link. |
sidebarId | string | undefined | Sidebar ID when type is 'docSidebar'. |
to | string | undefined | Internal URL when type is undefined. |
href | string | undefined | External URL when type is undefined. |
icon | string | undefined | Iconify icon identifier (e.g., 'lucide:rocket'). |
The type field accepts any of Docusaurus's standard navbar item kinds — 'doc', 'docSidebar', 'dropdown', 'localeDropdown', 'docsVersion', 'docsVersionDropdown', 'html', and 'search' — and Nova renders them as standard Docusaurus navbar items — except localeDropdown, which Nova restyles with an abbreviated locale label. The sidebarId, to, and href columns above cover the common 'docSidebar' and plain-link cases; other kinds take their own fields per the Docusaurus navbar documentation.
Docs
| Option | Type | Default | Description |
|---|---|---|---|
docs.versionPersistence | string | 'localStorage' | Where to persist the active version. |
docs.sidebar.hideable | boolean | false | Allow users to collapse the sidebar. |
docs.sidebar.autoCollapseCategories | boolean | false | Auto-collapse other categories when one is expanded. |
Blog
| Option | Type | Default | Description |
|---|---|---|---|
blog.sidebar.groupByYear | boolean | true | Group blog posts by year in the sidebar. |
blog.layout.heading | string | 'Blog' | Blog listing page heading. |
blog.layout.description | string | '' | Blog listing page description. |
blog.share.platforms | string[] | [] | Share button platforms. Accepts x, facebook, linkedin, reddit, copy. |
Blog Header Rendering
blog.layout.heading and blog.layout.description populate the page-level header that <BlogLayout> renders above the blog content on the blog index page. Other built-in blog pages (archive, author) render their own headers instead, and swizzle consumers can pass <BlogLayout showHeader> to opt into the header on a custom page, or pass a header ReactNode prop to override the default heading + description entirely.
Table of Contents
| Option | Type | Default | Description |
|---|---|---|---|
tableOfContents.minHeadingLevel | number | 2 | Minimum heading level to include in TOC. |
tableOfContents.maxHeadingLevel | number | 3 | Maximum heading level to include in TOC. |
Announcement Bar
| Option | Type | Default | Description |
|---|---|---|---|
announcementBar.id | string | — | Unique ID for dismiss persistence. |
announcementBar.content | string | — | HTML content of the announcement. |
announcementBar.backgroundColor | string | undefined | undefined | Background color override. |
announcementBar.textColor | string | undefined | undefined | Text color override. |
announcementBar.isCloseable | boolean | true | Whether users can dismiss the bar. |
Back to Top Button
| Option | Type | Default | Description |
|---|---|---|---|
backToTopButton | boolean | true | Show the back-to-top floating button. |
Error Pages
Customize copy on the 404, route-error, and React error-boundary surfaces. Each sub-key is optional; omit a key to use the preset's built-in defaults. Each leaf value is also optional, so you can override just the fields you care about.
Not Found (/404)
| Option | Type | Default | Description |
|---|---|---|---|
errorPages.notFound.title | string | — | Title shown above the 404 message. |
errorPages.notFound.description | string | — | Body text below the title. |
errorPages.notFound.backHomeLabel | string | — | Label of the back-home link. |
errorPages.notFound.backHomeHref | string | — | Href of the back-home link. Defaults to the site root when omitted. |
Error Page Content (route load errors)
| Option | Type | Default | Description |
|---|---|---|---|
errorPages.errorPageContent.title | string | — | Title shown when a route-level error is caught. |
errorPages.errorPageContent.retryLabel | string | — | Label of the retry button. |
Error (React error boundary)
| Option | Type | Default | Description |
|---|---|---|---|
errorPages.error.retryLabel | string | — | Label of the retry button shown by the top-level error boundary. |
Footer
Set to false to hide the footer entirely. Otherwise, provide an object:
| Option | Type | Default | Description |
|---|---|---|---|
footer.sections | Record<string, FooterLink[]> | {} | Named groups of footer links. |
footer.layout | Record<string, { title?, section }> | {} | Layout mapping for footer columns. |
footer.socialLinks | Array<{ icon: string, href: string, label: string }> | [] | Social media icon links. |
footer.copyright | string | undefined | undefined | Copyright text. |
footer.credit | boolean | true | Show "Built with Nova" credit. |
footer.cta | string | { label, href } | undefined | undefined | Call-to-action. Pass a string for a static label, or { label, href } to make the entire block clickable. |