Guides

Configuration

Configure your Barodoc site

Barodoc is configured through barodoc.config.json.

Full Example

{
  "name": "My Documentation",
  "logo": "/logo.svg",
  "favicon": "/favicon.ico",
  "theme": {
    "colors": {
      "accent": "#2563eb",
      "gray": "zinc"
    }
  },
  "i18n": {
    "defaultLocale": "en",
    "locales": ["en", "ko"],
    "labels": {
      "en": "English",
      "ko": "한국어"
    }
  },
  "navigation": [
    {
      "group": "Getting Started",
      "group:ko": "시작하기",
      "pages": ["introduction", "quickstart"]
    }
  ],
  "topbar": {
    "github": "https://github.com/user/repo"
  },
  "plugins": ["@barodoc/plugin-sitemap"]
}

Options

name

The site name displayed in the header.

logo

Path to the logo image in the public/ directory.

favicon

Path to the favicon in the public/ directory.

theme.colors

Customize the accent (primary) color and gray scale. Barodoc generates a full OKLCH-based 50–950 color palette from a single hex value.

{
  "theme": {
    "colors": {
      "accent": "#2563eb",
      "gray": "zinc"
    }
  }
}

accent — A hex color used to generate the primary/accent palette (links, buttons, active states). Defaults to #2563eb (blue).

gray — The neutral gray scale used for backgrounds, text, and borders. Accepts a preset name (zinc, slate, neutral, stone, gray) or a custom hex. Defaults to zinc.

You can also specify separate accent colors for light and dark modes:

{
  "theme": {
    "colors": {
      "accent": "#2563eb",
      "gray": "slate",
      "dark": {
        "accent": "#60a5fa"
      }
    }
  }
}

theme.fonts

Override heading and body fonts:

{
  "theme": {
    "fonts": {
      "heading": "Inter, sans-serif",
      "body": "Inter, sans-serif",
      "code": "JetBrains Mono, monospace"
    }
  }
}

theme.radius

Border radius for UI elements (e.g. "0.5rem", "8px").

tabs

Add top-level navigation links in the header for switching between content sections (Docs, Blog, API, Changelog, etc.):

{
  "tabs": [
    { "label": "Docs", "href": "/docs/introduction" },
    { "label": "Blog", "href": "/blog" },
    { "label": "API Reference", "href": "/docs/api/pet" },
    { "label": "Changelog", "href": "/changelog" }
  ]
}

Each tab has a label (display text) and href (link target). The active tab is highlighted based on the current URL. Tabs appear on desktop in the header and in the mobile navigation drawer. Optional — omit to show only the logo and topbar icons.

See Content Structure for details on how tabs connect different content types.

navigation

Define the sidebar navigation structure. Use group for the default locale and group:LOCALE for translated group names (see I18n).

Flat list — each entry in pages is a page slug:

{
  "navigation": [
    {
      "group": "Section Name",
      "group:ko": "섹션 이름",
      "pages": ["page-slug", "nested/page"]
    }
  ]
}

Sidebar hierarchy — an entry in pages can be an object with label and pages to show an expandable group in the sidebar. Use label:LOCALE for translated labels:

{
  "navigation": [
    {
      "group": "Guides",
      "group:ko": "가이드",
      "pages": [
        { "label": "Setup", "label:ko": "설정", "pages": ["guides/installation", "guides/configuration"] },
        "guides/deployment",
        "guides/i18n"
      ]
    }
  ]
}

• Page slugs map to files: introduction → docs/en/introduction.md, guides/installation → docs/en/guides/installation.md.
• Expandable item: { "label": "Setup", "pages": ["guides/installation", "guides/configuration"] } renders as a collapsible row “Setup” with two child links. The first child’s URL is used when the row is clicked.

sections

Add additional documentation sections (e.g. Help Center, Guides) with their own URL prefix and sidebar. The top-level navigation always applies to /docs/. Each entry in sections needs slug (URL prefix and content directory name), optional label (breadcrumb name), and navigation (same shape as top-level navigation).

{
  "sections": [
    {
      "slug": "help",
      "label": "Help Center",
      "navigation": [{ "group": "FAQ", "pages": ["general", "billing"] }]
    }
  ]
}

See Multiple Sections for directory layout and tabs setup.

topbar

Add links to the top navigation:

{
  "topbar": {
    "github": "https://github.com/user/repo",
    "discord": "https://discord.gg/invite",
    "twitter": "https://twitter.com/username"
  }
}

search

Enable or disable full-text search (Pagefind):

{
  "search": {
    "enabled": true
  }
}

blog

Enable or disable the blog content type. When enabled is true (default when blog content exists), the blog index and posts are available at /blog and /blog/[slug]. Set to false to hide blog routes.

{
  "blog": {
    "enabled": true
  }
}

versions

Configure a version switcher in the sidebar (e.g. for multiple doc versions). Each item has label (e.g. "v2") and path (URL segment, e.g. "v2" for /docs/v2/...). The switcher is hidden when there is only one version.

{
  "versions": [
    { "label": "v2", "path": "v2" },
    { "label": "v1", "path": "v1" }
  ]
}

customCss

Paths to additional CSS files (relative to project root or from public/). They are loaded after the theme styles:

{
  "customCss": ["./src/custom.css"]
}

site

The full URL of your deployed site (e.g. "https://docs.example.com"). Used for canonical URLs and OG meta tags.

base

Base path if the site is deployed under a subdirectory (e.g. "/docs").

lineNumbers

When true, code blocks render with line numbers.

{
  "lineNumbers": true
}

editLink

Show an “Edit this page” link on each documentation page. baseUrl is the GitHub (or other host) edit URL prefix:

{
  "editLink": {
    "baseUrl": "https://github.com/user/repo/edit/main/docs/src/content/docs/"
  }
}

lastUpdated

When true, shows a git-based “Last updated” timestamp in the page footer:

{
  "lastUpdated": true
}

Page contributors

Contributors are shown automatically at the bottom of every docs page — no configuration needed. Barodoc reads Git history to display the most recent editor’s avatar, with a +N badge for additional contributors. Hover the badge to see their names.

Avatars are fetched from GitHub (for noreply emails) or Gravatar. This feature requires the project to be a Git repository with commit history. See Content Structure for details.

announcement

Top-of-page banner for site-wide notices. Optionally links somewhere and can be dismissed:

{
  "announcement": {
    "text": "v2.0 is out!",
    "link": "https://github.com/user/repo/releases",
    "dismissible": true
  }
}

feedback

Page feedback widget (“Was this helpful?”). When endpoint is set, posts { page, helpful } JSON to that URL:

{
  "feedback": {
    "enabled": true,
    "endpoint": "https://api.example.com/feedback"
  }
}

plugins

Load Barodoc plugins (sitemap, analytics, etc.). In full custom (Astro) mode, install the plugin packages first (e.g. pnpm add @barodoc/plugin-sitemap).

{
  "plugins": [
    "@barodoc/plugin-sitemap",
    ["@barodoc/plugin-analytics", { "provider": "google", "id": "G-XXXXX" }]
  ]
}

Config reference

Quick reference for all supported keys. Optional keys can be omitted.