Skip to main content
BarodocBarodoc
GitHub
12 min read

가이드

Content Structure

docs, blog, API 레퍼런스, changelog 콘텐츠 타입이 어떻게 동작하는지

Barodoc는 네 가지 콘텐츠 타입을 기본 제공합니다: Docs, Blog, API Reference, Changelog. 각각 별도의 디렉터리, 스키마, 라우팅을 가지지만 — 동일한 사이트 셸(헤더, 테마, 검색)을 공유합니다.

전체 구조

my-project/
├── src/content/
│   ├── docs/           # 문서 페이지 (사이드바 네비게이션)
│   │   ├── en/
│   │   └── ko/
│   ├── blog/           # 블로그 포스트 (카드 그리드, 날짜순)
│   └── changelog/      # 릴리스 노트 (타임라인 뷰)
├── public/             # 정적 파일 (이미지, 로고, 파비콘)
├── barodoc.config.json # 사이트 설정, 네비게이션, 탭
└── openapi.yaml        # OpenAPI 스펙 (API 레퍼런스 사용 시)
콘텐츠 타입디렉터리라우트레이아웃
Docssrc/content/docs/{locale}//docs/{slug}사이드바 + 목차
Blogsrc/content/blog//blog/{slug}단일 컬럼 아티클
API ReferenceOpenAPI 스펙에서 자동 생성/docs/api/{slug}사이드바 + 플레이그라운드
Changelogsrc/content/changelog//changelog타임라인

탭으로 콘텐츠 타입 연결하기

tabs 설정으로 헤더에 최상위 네비게이션 링크를 추가하여 콘텐츠 타입 간 전환할 수 있습니다:

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

탭은 데스크톱 헤더와 모바일 네비게이션 드로어에 표시됩니다. 현재 URL에 따라 활성 탭이 하이라이트됩니다.

Info

tabs는 선택 사항입니다. 생략하면 헤더에 로고와 topbar 아이콘만 표시됩니다. docs 외에 다른 콘텐츠 타입이 있을 때 추가하세요.

Docs

문서는 기본 콘텐츠 타입입니다. locale 기반 폴더를 사용하며 사이드바는 barodoc.config.json에서 정의합니다.

디렉터리 구조

CLI 모드 (프로젝트 루트의 docs/):

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

수동 Astro 모드 (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 폴더(en, ko 등)는 필수입니다 — 단일 언어 사이트도 하나 필요합니다.
  • 파일 경로 = URL slug: guides/installation.mdx → /docs/guides/installation.
  • 파일명은 소문자와 하이픈 사용 권장 (code-group.mdx, CodeGroup.mdx X).

사이드바 네비게이션

barodoc.config.json의 navigation 배열로 사이드바를 정의합니다. locale과 .mdx를 뺀 slug를 사용합니다:

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

동일한 slug를 모든 locale에서 공유하며, 각 locale 폴더에 해당 파일을 둡니다.

Frontmatter

---
title: Installation
description: Barodoc 설치 방법
tags: [setup, cli]
related: [quickstart, guides/configuration]
category: guides
difficulty: beginner
---
필드타입설명
titlestring페이지 제목 (브라우저 탭, 사이드바, 메타).
descriptionstring메타 설명.
tagsstring[]검색 및 필터링용 분류 태그.
relatedstring[]관련 페이지 slug.
categorystring카테고리 직접 지정 (생략 시 nav 그룹에서 자동 감지).
difficulty"beginner" | "intermediate" | "advanced"콘텐츠 난이도.
api_referencebooleanAPI 레퍼런스 문서 표시.
lastUpdateddate최종 수정일 수동 지정.

Blog

블로그 포스트는 src/content/blog/에 둡니다 (locale 하위 폴더 없음). 날짜순 정렬되어 /blog에 카드 그리드로 표시됩니다.

디렉터리 구조

src/content/blog/
├── introducing-barodoc.mdx    → /blog/introducing-barodoc
├── v6-release.mdx             → /blog/v6-release
└── writing-great-docs.mdx     → /blog/writing-great-docs

블로그 포스트 만들기

src/content/blog/에 .mdx (또는 .md) 파일을 생성합니다:

---
title: "Barodoc 소개"
description: "Astro 기반 제로 설정 문서 프레임워크."
excerpt: "몇 초 만에 아름다운 문서를."
date: 2026-02-01
author: "Barodoc Team"
image: "/images/blog-cover.png"
tags: ["announcement", "release"]
---

블로그 콘텐츠를 작성합니다. docs에서 쓰는 MDX 컴포넌트
(Callout, Tabs, CodeGroup 등)를 모두 사용할 수 있습니다.

Frontmatter

필드타입설명
titlestring포스트 제목 (필수).
descriptionstring메타 설명.
excerptstring블로그 인덱스 카드에 표시되는 요약.
datedate게시 날짜. 정렬에 사용.
authorstring작성자 이름.
avatarstring작성자 아바타 이미지 URL. 인덱스와 포스트 페이지에서 작성자 이름 옆에 표시.
imagestring커버 이미지 경로 (인덱스 카드와 포스트 페이지에 표시).
tagsstring[]카드와 포스트 헤더에 배지로 표시되는 태그.

Tip

/blog 인덱스 페이지는 자동 생성됩니다. 직접 만들 필요 없이 src/content/blog/에 포스트를 추가하면 바로 표시됩니다.

API Reference

API 레퍼런스 페이지는 두 가지 방법으로 만들 수 있습니다: OpenAPI 스펙에서 자동 생성 (권장) 또는 API 컴포넌트를 사용한 수동 작성.

방법 1: OpenAPI 플러그인 (권장)

@barodoc/plugin-openapi가 OpenAPI 스펙을 읽고 인터랙티브 플레이그라운드가 포함된 페이지를 자동 생성합니다. 단일 스펙 또는 여러 스펙을 사용할 수 있습니다:

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

여러 API가 있는 프로젝트는 specFile에 배열을 전달합니다:

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

생성된 페이지는 /docs/api/... 경로에 나타나며 일반 docs와 함께 사이드바에 표시됩니다. 멀티 스펙 설정을 포함한 전체 설정은 OpenAPI 플러그인 가이드를 참고하세요.

방법 2: 수동 API 컴포넌트

커스텀 API 문서에는 ApiEndpoint, ApiParams, ApiParam, ApiResponse 컴포넌트를 MDX에서 직접 사용합니다. API Reference Components를 참고하세요.

Changelog

체인지로그 항목은 src/content/changelog/에 둡니다. /changelog에 타임라인으로 표시됩니다.

디렉터리 구조

src/content/changelog/
├── v2.0.0.mdx    → /changelog에 표시
├── v1.5.0.mdx
└── v1.0.0.mdx

체인지로그 항목 만들기

---
version: "2.0.0"
date: 2026-02-15
title: "헤더 탭 & 블로그 개선"
---

### 새로운 기능
- 최상위 네비게이션을 위한 설정 가능한 헤더 탭
- 블로그 포스트의 코드 복사 버튼

### 버그 수정
- 모바일 네비게이션 스크롤 동작 수정

Frontmatter

필드타입설명
versionstring버전 번호 (필수).
datedate릴리스 날짜 (필수). 정렬에 사용.
titlestring선택적 릴리스 제목.

종합 예제

모든 콘텐츠 타입을 설정한 일반적인 Barodoc 사이트:

{
  "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", "label:ko": "설정", "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" }]
  ]
}

Guides 그룹은 사이드바 계층 예시입니다. { "label": "Setup", "pages": [...] } 형태로 접을 수 있는 행을 만들 수 있습니다. 자세한 내용은 설정 → 네비게이션을 참고하세요.

my-project/
├── src/content/
│   ├── docs/en/              # ← 사이드바 문서
│   │   ├── introduction.mdx
│   │   └── guides/...
│   ├── blog/                 # ← 블로그 포스트
│   │   ├── hello-world.mdx
│   │   └── v2-release.mdx
│   └── changelog/            # ← 릴리스 노트
│       ├── v2.0.0.mdx
│       └── v1.0.0.mdx
├── openapi.yaml              # ← API 스펙
├── barodoc.config.json
└── public/
    └── logo.svg

콘텐츠 타입 독립성

각 콘텐츠 타입은 선택적이고 독립적입니다:

  • Docs만 — blog/나 changelog/ 폴더를 만들지 않고 tabs도 생략. 기본값입니다.
  • Docs + Blog — src/content/blog/를 추가하고 Blog tabs 항목 추가.
  • Docs + API — OpenAPI 플러그인을 추가하고 API 페이지를 navigation에 포함.
  • 네 가지 모두 — 모든 폴더를 만들고 tabs로 전체 네비게이션 설정.

테마는 없는 컬렉션을 자동으로 처리합니다 — blog/가 없으면 /blog에서 에러 대신 “No posts yet”을 표시합니다.

페이지 기여자

Barodoc은 모든 문서 페이지 하단에 Git 히스토리 기반으로 Contributors 섹션을 자동 표시합니다.

  • 가장 최근 수정자의 아바타가 표시됩니다
  • 추가 기여자가 있으면 아바타 옆에 +N 카운트 배지가 나타납니다
  • 카운트 배지에 마우스를 올리면 나머지 기여자 이름이 표시됩니다
  • 아바타는 GitHub (@users.noreply.github.com 이메일) 또는 Gravatar에서 가져옵니다

별도 설정 없이 자동으로 동작합니다. 빌드 시 git log에서 읽기 때문에 Git 저장소에 커밋 히스토리가 있어야 합니다.

MDX와 컴포넌트

  • Markdown (.md) 또는 MDX (.mdx)를 모든 콘텐츠 타입에 사용할 수 있습니다.
  • 테마 컴포넌트(Tabs, Accordion, Callout 등)는 docs와 블로그 포스트 모두에서 동작합니다.
  • 인터랙티브 컴포넌트는 hydration을 위해 client:load가 필요합니다 (예: <Tabs client:load ... />).
  • 전체 목록은 Components를 참고하세요.

정적 파일

이미지 등 정적 파일은 **public/**에 두고 사이트 루트 기준 경로로 참조합니다:

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

Linked pages