Guides

Installation

Install Barodoc: prerequisites, CLI (zero-config), existing folder, or manual Astro setup

Two ways to use Barodoc: CLI (zero-config) for a docs-only project, or Manual (Astro) for a full Astro app.

Prerequisites

• Node.js 20 or higher (node -v)
• Package manager: pnpm (recommended), npm, or yarn

Optional: install the CLI globally so you can run barodoc without npx:

npm install -g barodoc
# or
pnpm add -g barodoc

Then use barodoc serve, barodoc build, etc. from any directory. Without a global install, use npx barodoc from the project folder.

CLI (zero-config, recommended for new docs)

No package.json or Astro config in your repo. You only have docs/, public/, and barodoc.config.json.

Option A: Create a new project

pnpm create barodoc my-docs
cd my-docs

Option B: Use an existing folder

If you already have a repo (e.g. only Markdown files), initialize Barodoc in place:

cd my-existing-repo
barodoc init
# or: npx barodoc init

This adds barodoc.config.json, a default docs/en/introduction.md, and updates .gitignore. It does not overwrite an existing config. Put your content under docs/<locale>/ and add slugs to navigation in the config.

Structure (after create or init)

No src/ or astro.config.mjs in the project. The CLI generates a temporary Astro project under .barodoc/ when you run commands.

Commands

# Development (default port 4321)
npx barodoc serve

# Custom port, host, or config
npx barodoc serve --port 3000
npx barodoc serve --host
npx barodoc serve --config custom.config.json

# Production build (output: dist/)
npx barodoc build

# Preview production build
npx barodoc preview

You do not need to run npm install or pnpm install inside the project in Quick mode; npx barodoc uses the bundled CLI and plugins.

Troubleshooting (CLI)

• Port in use: use --port to pick another port, or stop the process using the port.
• Stale cache / weird build: run with --clean to force reinstall of the temporary project:
  npx barodoc serve --clean or npx barodoc build --clean.
• Config not found: pass the path explicitly: npx barodoc serve --config ./barodoc.config.json.

Manual installation (Astro integration)

Use this when you want a normal Astro project (e.g. custom routes, other integrations). Content lives under src/content/docs/, and you run pnpm dev / pnpm build.

1. Create Astro project

pnpm create astro@latest my-docs
cd my-docs

2. Install Barodoc packages

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

3. Configure Astro

In astro.config.mjs:

import { defineConfig } from "astro/config";
import barodoc from "@barodoc/core";
import docsTheme from "@barodoc/theme-docs";

export default defineConfig({
  integrations: [
    barodoc({
      config: "./barodoc.config.json",
      theme: docsTheme(),
    }),
  ],
});

4. Create config file

Create barodoc.config.json in the project root:

{
  "name": "My Docs",
  "logo": "/logo.svg",
  "navigation": [
    {
      "group": "Getting Started",
      "pages": ["introduction", "quickstart"]
    }
  ],
  "i18n": {
    "defaultLocale": "en",
    "locales": ["en"]
  }
}

5. Add content

Create src/content/docs/en/introduction.mdx (and optionally other locales under src/content/docs/ko/, etc.). See Content structure for layout and slugs.

---
title: Introduction
description: Welcome to the docs
---

# Welcome

Your documentation starts here.

6. Run the project

pnpm dev
pnpm build

Content structure and URL rules are the same as in CLI mode; only the directory is src/content/docs/ instead of docs/.

Plugins in manual mode

Install plugin packages in the project, then list them in barodoc.config.json:

pnpm add @barodoc/plugin-sitemap @barodoc/plugin-search

See Recommended plugins and Plugins for options.

Next steps

• Quick Start — Run the dev server and add pages
• Configuration — Theme, search, i18n, site URL
• Recommended plugins — Which plugins to add by use case
• Deployment — Build and deploy to static hosts