문서 트러블슈팅

빠른 점검

pnpm check:docs
pnpm docs:linkcheck
cd docs && pnpm dlx mintlify broken-links
cd docs && pnpm dlx mintlify validate

명시적으로 docs로 이동하는 명령이 아니면 저장소 루트에서 실행하세요.

상대 링크 깨짐

증상: 링크 체크가 파일 누락을 보고함.해결: Mintlify 라우트(/path)를 사용하고, docs/docs.json 네비게이션과 경로를 일치시키며, 페이지 이동/이름 변경 후 오래된 경로를 제거합니다.

네비게이션에 페이지 미노출

증상: 파일은 있는데 사이드바/탭에 표시되지 않음.해결: docs/docs.json에 페이지 라우트를 추가하고 mintlify validate로 구조 무결성을 확인합니다.

Markdown lint 실패

증상: pnpm check:docs가 포맷/헤딩 규칙으로 실패함.해결: linter 출력 라인 기준으로 수정하고, 헤딩 계층/리스트 형식을 일관되게 유지하며, 가능한 Mintlify 기본 컴포넌트를 사용합니다.

Mintlify 검증 실패

증상: markdownlint는 통과했는데 mintlify validate 실패.해결: 지원되지 않는 컴포넌트 문법, docs/docs.json의 탭/그룹/페이지 매핑, 존재하지 않는 라우트 링크를 점검합니다.

포맷/링크 검증

pnpm check:docs와 pnpm docs:linkcheck 실행

Mintlify 라우팅/구조 검증

cd docs && pnpm dlx mintlify broken-links 및 cd docs && pnpm dlx mintlify validate 실행

핵심 경로 스팟체크