Support

Upgrade Guide

How to upgrade between major Barodoc versions

This guide covers upgrading between major Barodoc versions. For minor/patch updates, simply update your CLI or dependencies — no migration steps needed.

Upgrading to v7.x (from v6.x)

Version 7 introduces Quick Mode’s new architecture (programmatic Astro API), the plugin system, and multi-section documentation.

What Changed

Area	v6.x	v7.x
Quick Mode	Creates `package.json` + `node_modules`	Creates temporary `.barodoc/` directory
Plugins	Built-in only	Configurable plugin system
Content	`docs/` only	`docs/`, `blog/`, `changelog/`, `help/`, `pages/`
Navigation	Single section	Multi-section with `sections` config
Standalone pages	Not supported	`pages/` directory

Migration Steps

Update the CLI

If using Quick Mode, just run the latest version:

npx barodoc@latest serve docs

Clean up old artifacts

Remove the old generated files from your project:

rm -rf node_modules package.json package-lock.json

Add .barodoc/ to your .gitignore:

.barodoc/
dist/

Update plugin configuration

Plugins are now declared in barodoc.config.json instead of being implicitly enabled:

{
  "plugins": [
    "@barodoc/plugin-sitemap",
    "@barodoc/plugin-search"
  ]
}

Test your site

Run the dev server and check that all pages render correctly:

npx barodoc serve

Content files unchanged

Your Markdown and MDX files don’t need any changes. Only the CLI invocation and config format have changed.

Full Custom Mode

If you’re using Full Custom Mode (with astro.config.mjs):

Update your dependencies:

pnpm update @barodoc/core @barodoc/theme-docs

The theme integration API is unchanged — docsTheme() works the same way.
If you want multi-section support, add sections to your barodoc.config.json and create matching content collections in src/content/config.ts.

Upgrading to v6.x (from v5.x)

Version 6 upgraded to Astro 5 and introduced the component library.

What Changed

Astro 5 — Content Layer API replaces the old content collections
New components — Callout, Card, Steps, CodeGroup, and more
Dark mode — Built-in theme toggle
Reading time — Automatic reading time estimates

Migration Steps

Update dependencies

pnpm update @barodoc/core @barodoc/theme-docs astro

Update content config

Replace defineCollection with the new Astro 5 content config format if you’re using Full Custom Mode. The glob() loader is now the default.

Update component imports

Component imports changed from deep paths to a single entry point:

- import Callout from "@barodoc/theme-docs/components/Callout";
+ import { Callout } from "@barodoc/theme-docs";

Version Support Policy

Version	Status	Node.js	Astro
7.x	Current	20+	5.x
6.x	Maintenance (security fixes only)	18+	5.x
5.x	End of life	16+	4.x

We recommend always running the latest version. Quick Mode users get automatic updates via npx.