Skip to main content
BarodocBarodoc
GitHub
6 min read

가이드

설정

Barodoc 설정 가이드

barodoc.config.json 파일로 사이트를 설정합니다.

기본 설정

{
  "name": "내 문서",
  "logo": "/logo.svg",
  "favicon": "/favicon.ico",
  "navigation": [
    {
      "group": "시작하기",
      "pages": ["introduction", "quickstart"]
    }
  ]
}

테마 설정

강조색(accent)과 회색(gray) 스케일을 설정합니다. 하나의 hex 값으로 OKLCH 기반 50~950 팔레트가 자동 생성됩니다.

{
  "theme": {
    "colors": {
      "accent": "#2563eb",
      "gray": "zinc"
    }
  }
}

accent — 링크, 버튼, 활성 상태에 사용되는 강조색 hex 값. 기본값: #2563eb (파란색).

gray — 배경, 텍스트, 보더에 사용되는 회색 스케일. 프리셋명(zinc, slate, neutral, stone, gray) 또는 커스텀 hex. 기본값: zinc.

라이트/다크 모드별 다른 강조색을 지정할 수 있습니다:

{
  "theme": {
    "colors": {
      "accent": "#2563eb",
      "gray": "slate",
      "dark": {
        "accent": "#60a5fa"
      }
    }
  }
}

폰트도 커스터마이징할 수 있습니다:

{
  "theme": {
    "fonts": {
      "heading": "Pretendard, sans-serif",
      "body": "Pretendard, sans-serif",
      "code": "JetBrains Mono, monospace"
    }
  }
}

탭 (tabs)

헤더에 최상위 네비게이션 링크를 추가하여 콘텐츠 섹션(Docs, Blog, API, Changelog 등) 간 전환할 수 있습니다:

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

각 탭은 label(표시 텍스트)과 href(링크 대상)를 가집니다. 현재 URL에 따라 활성 탭이 하이라이트됩니다. 탭은 데스크톱 헤더와 모바일 네비게이션 드로어에 표시됩니다. 선택 사항 — 생략하면 로고와 topbar 아이콘만 표시합니다.

자세한 내용은 Content Structure에서 각 콘텐츠 타입이 어떻게 연결되는지 확인하세요.

네비게이션

사이드바 구조를 정의합니다. pages에는 페이지 슬러그 문자열 또는 { "label": "이름", "pages": ["slug1", "slug2"] } 형태의 접기 항목을 넣을 수 있습니다. label:en 등으로 다국어 라벨 지원.

{
  "navigation": [
    {
      "group": "시작하기",
      "group:en": "Getting Started",
      "pages": ["introduction", "quickstart"]
    },
    {
      "group": "가이드",
      "group:en": "Guides",
      "pages": [
        { "label": "설정", "label:en": "Setup", "pages": ["guides/installation", "guides/configuration"] },
        "guides/deployment"
      ]
    }
  ]
}

상단 바

소셜 링크를 추가할 수 있습니다:

{
  "topbar": {
    "github": "https://github.com/org/repo",
    "discord": "https://discord.gg/invite"
  }
}

검색

Pagefind 검색을 켜거나 끕니다:

{
  "search": {
    "enabled": true
  }
}

customCss

테마 스타일 이후에 로드할 추가 CSS 파일 경로입니다 (프로젝트 루트 또는 public/ 기준):

{
  "customCss": ["./src/custom.css"]
}

theme.radius

UI 요소의 border radius (예: "0.5rem", "8px").

site

배포된 사이트의 전체 URL (예: "https://docs.example.com"). 정규 URL 및 OG 메타 태그에 사용.

base

사이트가 서브디렉토리에 배포될 경우의 기본 경로 (예: "/docs").

lineNumbers

true로 설정하면 코드 블록에 줄 번호를 표시합니다:

{
  "lineNumbers": true
}

각 문서 페이지에 “Edit this page” 링크를 표시합니다. baseUrl은 GitHub(또는 다른 호스트) 편집 URL 접두사입니다:

{
  "editLink": {
    "baseUrl": "https://github.com/user/repo/edit/main/docs/src/content/docs/"
  }
}

lastUpdated

true로 설정하면 페이지 하단에 git 기반 “최종 수정일” 타임스탬프를 표시합니다:

{
  "lastUpdated": true
}

페이지 기여자

문서 페이지 하단에 기여자가 자동으로 표시됩니다 — 별도 설정이 필요 없습니다. Barodoc이 Git 히스토리를 읽어 가장 최근 수정자의 아바타를 보여주고, 추가 기여자가 있으면 +N 배지로 표시합니다. 배지에 마우스를 올리면 이름이 표시됩니다.

아바타는 GitHub (noreply 이메일) 또는 Gravatar에서 가져옵니다. 이 기능은 프로젝트가 커밋 히스토리가 있는 Git 저장소여야 합니다. 자세한 내용은 콘텐츠 구조를 참고하세요.

announcement

사이트 상단에 공지 배너를 표시합니다. 링크와 닫기 기능을 옵션으로 설정할 수 있습니다:

{
  "announcement": {
    "text": "v2.0 출시!",
    "link": "https://github.com/user/repo/releases",
    "dismissible": true
  }
}

feedback

페이지 피드백 위젯(“도움이 되었나요?”). endpoint 설정 시 해당 URL로 { page, helpful } JSON을 POST합니다:

{
  "feedback": {
    "enabled": true,
    "endpoint": "https://api.example.com/feedback"
  }
}

플러그인

플러그인으로 기능을 확장합니다:

{
  "plugins": [
    "@barodoc/plugin-sitemap",
    ["@barodoc/plugin-analytics", { "provider": "google", "id": "G-XXXXX" }]
  ]
}

Linked pages