가이드

문제 해결

Barodoc 사용 시 자주 발생하는 문제와 해결 방법을 안내합니다.

자주 발생하는 문제와 해결 방법입니다.

설정 & 설치

'Config file not found' 에러

프로젝트 루트에 barodoc.config.json이 있는지 확인하세요.

ls barodoc.config.json

# 또는 경로를 명시적으로 지정
barodoc serve --config ./path/to/barodoc.config.json

Node.js 버전 에러

Barodoc은 Node.js 20 이상이 필요합니다.

node --version

# nvm 사용 시
nvm install 20 && nvm use 20

포트 충돌

barodoc serve --port 4322

사이드바에 페이지가 안 보임

barodoc.config.json의 navigation에 페이지를 추가해야 합니다:

{
  "navigation": [
    {
      "group": "가이드",
      "pages": ["guides/my-new-page"]
    }
  ]
}

경로는 로캘 폴더 기준 상대 경로이며 확장자는 제외합니다.

MDX 컴포넌트가 렌더링되지 않음

파일 상단에 import를 확인하세요:

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

Warning

컴포넌트를 사용하려면 .md가 아닌 .mdx 확장자를 사용해야 합니다.

이미지가 로드되지 않음

정적 에셋은 public/ 디렉토리에 넣고 절대 경로로 참조하세요:

![스크린샷](/images/screenshot.png)

GitHub Pages 배포 후 빈 페이지

서브 경로에 배포하는 경우 base 옵션을 설정하세요:

{
  "base": "/my-docs"
}