Make sure barodoc.config.json exists in your project root (or the directory you’re running from).

# Verify the file exists
ls barodoc.config.json

# Or specify the config path explicitly
barodoc serve --config ./path/to/barodoc.config.json

Barodoc requires Node.js 20 or later. Check your version:

node --version

If you’re using a version manager, switch to Node 20+:

# nvm
nvm install 20
nvm use 20

# fnm
fnm use 20

Use a different port:

barodoc serve --port 4322

Or kill the process using the default port:

lsof -ti:4321 | xargs kill -9

Pages must be listed in barodoc.config.json under navigation:

{
  "navigation": [
    {
      "group": "Guides",
      "pages": ["guides/my-new-page"]
    }
  ]
}

The page path should match the file path relative to your docs locale folder, without the extension. For example, docs/en/guides/my-new-page.mdx becomes "guides/my-new-page".

Make sure you’re importing the component at the top of your MDX file:

import { Callout, Card } from "@barodoc/theme-docs";

<Callout type="tip">
  This will render correctly.
</Callout>

If you’re in Full Custom Mode (with astro.config.mjs), make sure your content collections are defined in src/content/config.ts:

import { defineCollection, z } from "astro:content";

const docsCollection = defineCollection({
  type: "content",
  schema: z.object({
    title: z.string(),
    description: z.string().optional(),
  }),
});

export const collections = { docs: docsCollection };

In Quick Mode, this is handled automatically.

Static assets should be placed in the public/ directory:

my-docs/
├── public/
│   └── images/
│       └── screenshot.png   ← here
└── docs/
    └── en/
        └── guide.mdx        ← references /images/screenshot.png

Reference them with absolute paths:

![Screenshot](/images/screenshot.png)

Ensure your folder structure matches the configured locales:

{
  "i18n": {
    "defaultLocale": "en",
    "locales": ["en", "ko"]
  }
}

Each locale needs its own directory with matching file paths:

docs/
├── en/
│   └── guides/setup.mdx
└── ko/
    └── guides/setup.mdx   ← same path structure

The language switcher only appears when more than one locale is configured in barodoc.config.json. Make sure locales has at least two entries.

Search is powered by Pagefind, which indexes your site during the build step. Make sure you:

1. Run a full build: barodoc build
2. Preview the build: barodoc preview

Search won’t work in dev mode — it only works on built output.

Check your plugin configuration:

{
  "plugins": [
    ["@barodoc/plugin-openapi", {
      "specFile": "openapi.yaml",
      "basePath": "api"
    }]
  ]
}

The specFile path is relative to your project root. Verify the file exists and is valid YAML/JSON.

Ensure you’ve provided the correct tracking ID for your provider:

{
  "plugins": [
    ["@barodoc/plugin-analytics", {
      "google": { "measurementId": "G-XXXXXXXXXX" },
      "plausible": { "domain": "docs.example.com" }
    }]
  ]
}

Analytics scripts are only injected in production builds, not during development.

If your docs are hosted at a subpath (e.g., username.github.io/my-docs/), set the base option:

{
  "base": "/my-docs"
}

Without this, asset paths will resolve incorrectly.

Barodoc generates static HTML files. Configure your hosting provider to serve index.html for directory routes:

• Netlify: Add _redirects file with /* /index.html 200
• Vercel: Works automatically
• GitHub Pages: Works automatically for static files