Guides

Content Structure

How docs, blog, API reference, and changelog content types work together

Barodoc supports four content types out of the box: Docs, Blog, API Reference, and Changelog. Each has its own directory, schema, and routing — but they share the same site shell (header, theme, search).

Overview

my-project/
├── src/content/
│   ├── docs/           # Documentation pages (sidebar navigation)
│   │   ├── en/
│   │   └── ko/
│   ├── blog/           # Blog posts (card grid, date-sorted)
│   └── changelog/      # Release notes (timeline view)
├── public/             # Static assets (images, logo, favicon)
├── barodoc.config.json # Site config, navigation, tabs
└── openapi.yaml        # OpenAPI spec (if using API reference)

Connecting content types with tabs

Use the tabs config to add top-level navigation links in the header so users can switch between content types:

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

Tabs appear in the header on desktop and in the mobile navigation drawer. The active tab is highlighted based on the current URL.

Docs

Documentation is the primary content type. It uses locale-based folders and a sidebar defined in barodoc.config.json.

Directory layout

CLI mode (docs/ at project root):

docs/
├── en/
│   ├── introduction.mdx    → /docs/introduction
│   └── guides/
│       └── installation.mdx → /docs/guides/installation
└── ko/
    └── ...

Manual Astro mode (src/content/docs/):

src/content/docs/
├── en/
│   ├── introduction.mdx       # /docs/introduction
│   ├── quickstart.mdx          # /docs/quickstart
│   └── guides/
│       ├── installation.mdx    # /docs/guides/installation
│       └── deployment.mdx      # /docs/guides/deployment
└── ko/
    ├── introduction.mdx        # /ko/docs/introduction
    └── guides/
        └── installation.mdx    # /ko/docs/guides/installation

• Locale folder (en, ko, etc.) is required — even single-language sites need one.
• File path = URL slug: guides/installation.mdx → /docs/guides/installation.
• Use lowercase and hyphens for file names (code-group.mdx, not CodeGroup.mdx).

Sidebar navigation

In barodoc.config.json, the navigation array defines the sidebar. Use slugs without locale and without .mdx:

{
  "navigation": [
    {
      "group": "Getting Started",
      "group:ko": "시작하기",
      "pages": ["introduction", "quickstart"]
    },
    {
      "group": "Guides",
      "group:ko": "가이드",
      "pages": ["guides/installation", "guides/configuration"]
    }
  ]
}

The same slug is shared across all locales — each locale has its own file under its folder.

Frontmatter

---
title: Installation
description: Install Barodoc in your project
tags: [setup, cli]
related: [quickstart, guides/configuration]
category: guides
difficulty: beginner
---

Blog

Blog posts live in src/content/blog/ (no locale subfolders). They are date-sorted and displayed in a card grid at /blog.

Directory layout

src/content/blog/
├── introducing-barodoc.mdx    → /blog/introducing-barodoc
├── v6-release.mdx             → /blog/v6-release
└── writing-great-docs.mdx     → /blog/guide-writing   (with urlSlug in frontmatter)

By default the URL slug is the file name without extension. To use a custom URL, add urlSlug in frontmatter (e.g. urlSlug: "guide-writing").

Creating a blog post

Create an .mdx (or .md) file in src/content/blog/:

---
title: "Introducing Barodoc"
description: "Zero-config documentation framework built on Astro."
excerpt: "Beautiful docs in seconds."
date: 2026-02-01
author: "Barodoc Team"
image: "/images/blog-cover.png"
tags: ["announcement", "release"]
---

Your blog content here. You can use all the same MDX components
(Callout, Tabs, CodeGroup, etc.) available in docs.

Frontmatter

API Reference

API reference pages can be created two ways: auto-generated from an OpenAPI spec (recommended) or manually written using API components.

Option 1: OpenAPI plugin (recommended)

The @barodoc/plugin-openapi reads your OpenAPI spec and generates pages automatically with an interactive playground. You can use a single spec file or multiple specs:

{
  "plugins": [
    ["@barodoc/plugin-openapi", {
      "specFile": "openapi.yaml",
      "basePath": "api",
      "groupBy": "tags",
      "playground": true
    }]
  ],
  "navigation": [
    {
      "group": "API Reference",
      "pages": ["api/pet", "api/store", "api/user"]
    }
  ]
}

For projects with multiple APIs, pass an array to specFile:

{
  "plugins": [
    ["@barodoc/plugin-openapi", {
      "specFile": [
        { "file": "api/public.yaml", "basePath": "api/public" },
        { "file": "api/admin.yaml", "basePath": "api/admin" }
      ],
      "playground": true
    }]
  ]
}

Generated pages appear under /docs/api/... and are listed in the sidebar alongside regular docs. See the OpenAPI plugin guide for full setup including multi-spec configuration.

Option 2: Manual API components

For custom API documentation, use the ApiEndpoint, ApiParams, ApiParam, and ApiResponse components directly in MDX. See API Reference Components.

Changelog

Changelog entries live in src/content/changelog/. They are displayed as a timeline at /changelog.

Directory layout

src/content/changelog/
├── v2.0.0.mdx    → shown on /changelog
├── v1.5.0.mdx
└── v1.0.0.mdx

Creating a changelog entry

---
version: "2.0.0"
date: 2026-02-15
title: "Header tabs & blog improvements"
---

### New features
- Configurable header tabs for top-level navigation
- Code copy button in blog posts

### Bug fixes
- Fixed mobile navigation scroll behavior

Frontmatter

Putting it all together

A typical Barodoc site with all content types configured:

{
  "name": "My Project",
  "logo": "/logo.svg",

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

  "navigation": [
    {
      "group": "Getting Started",
      "pages": ["introduction", "quickstart"]
    },
    {
      "group": "Guides",
      "pages": [
        { "label": "Setup", "pages": ["guides/installation", "guides/configuration"] },
        "guides/deployment"
      ]
    },
    {
      "group": "API Reference",
      "pages": ["api/overview", "api/users", "api/auth"]
    }
  ],
  "plugins": [
    "@barodoc/plugin-sitemap",
    ["@barodoc/plugin-openapi", { "specFile": "openapi.yaml", "basePath": "api" }]
  ]
}

The Guides group shows sidebar hierarchy: { "label": "Setup", "pages": [...] } renders as an expandable row. See Configuration for details.

my-project/
├── src/content/
│   ├── docs/en/              # ← Sidebar docs
│   │   ├── introduction.mdx
│   │   └── guides/...
│   ├── blog/                 # ← Blog posts
│   │   ├── hello-world.mdx
│   │   └── v2-release.mdx
│   └── changelog/            # ← Release notes
│       ├── v2.0.0.mdx
│       └── v1.0.0.mdx
├── openapi.yaml              # ← API spec
├── barodoc.config.json
└── public/
    └── logo.svg

Content type independence

Each content type is optional and independent:

• Docs only — Don’t create blog/ or changelog/ folders, omit tabs. This is the default.
• Docs + Blog — Add src/content/blog/ and a tabs entry for Blog.
• Docs + API — Add the OpenAPI plugin and include API pages in navigation.
• All four — Create all folders and configure tabs for full navigation.

The theme automatically handles missing collections gracefully — if blog/ doesn’t exist, /blog shows “No posts yet” instead of an error.

Page contributors

Barodoc automatically displays a Contributors section at the bottom of every docs page, showing who has edited the file based on Git history.

• The most recent contributor’s avatar is shown
• If there are additional contributors, a +N count badge appears next to the avatar
• Hovering the count badge shows the names of the other contributors
• Avatars are fetched from GitHub (for @users.noreply.github.com emails) or Gravatar

This feature works automatically — no configuration needed. It reads from git log at build time, so the repository must be a Git repo with commit history.

MDX and components

• Use Markdown (.md) or MDX (.mdx) for all content types.
• Theme components (Tabs, Accordion, Callout, etc.) work in docs and blog posts alike.
• Interactive components need client:load for hydration (e.g. <Tabs client:load ... />).
• See Components for the full list.

Static assets

Put images and other static files in public/. Reference by path from the site root:

• public/logo.svg → /logo.svg
• public/images/diagram.png → /images/diagram.png