Skip to main content
BarodocBarodoc
GitHub
4 min read

가이드

그래프와 위키 스타일 링크

위키링크, 내부 마크다운 링크, 링크 그래프, CI 검사

Barodoc 문서 테마는 옵시디언 볼트처럼 [[...]] 위키링크, 일반 마크다운 링크, MDX <a href> 를 모두 링크 그래프에 넣고, 필요하면 풀리지 않은 링크를 보고하며, 각 문서 하단에 연결된 문서를 표시합니다.

위키링크 [[...]]

.md / .mdx에서 옵시디언 스타일을 쓸 수 있습니다.

[[guides/i18n]] 문서를 참고하세요.

[[introduction|시작하기]]
  • 소스 파일과 같은 섹션 안에서만 연결됩니다 (docs ↔ docs 등).
  • 별칭: [[페이지|표시 텍스트]]
  • 헤딩: [[페이지#섹션]] — 문서는 해석되고 URL에 # 프래그먼트가 붙습니다.
  • 대상을 찾지 못하면 본문에 [[...]] 그대로 두고, graph.json과 문서 하단에 broken으로 표시됩니다.

해석 규칙은 소스 파일의 로케일을 기준으로 합니다. 자세한 순서는 wikiIndex.ts를 참고하세요.

마크다운 링크 [텍스트](url)

다른 문서를 가리키면 그래프에 엣지로 들어갑니다.

  • 사이트 경로: /docs/ko/guides/cli
  • 상대 경로: ./other-page, ../folder/page
  • barodoc.config.json의 site와 같은 도메인의 https:// URL

외부 도메인은 그래프에 넣지 않습니다. mailto:, tel:, javascript: 는 무시합니다.

MDX <a href="...">

MDX의 앵커 태그 href도 마크다운 링크와 동일하게 스캔합니다.

그래프 페이지 /graph

테마가 /graph 라우트를 추가합니다(Sigma.js). /graph.json 을 불러와 노드·엣지를 그립니다.

  • ?focus= — 특정 문서와 이웃만 강조 (예: /graph?focus=ko/guides/landing).

graph.json

개발 중에는 public/graph.json 에 생성되고, 프로덕션 빌드 시 사이트 루트로 복사됩니다.

  • nodes, edges, broken (선택) 필드를 포함합니다.

문서 하단 «연결된 문서»

각 문서마다(에셋 뷰어 제외):

  • 이 문서에서 링크 — 나가는 링크
  • 이 문서를 가리키는 페이지 — 들어오는 링크
  • 풀리지 않은 내부 링크 — 해당 페이지에만 노란 박스로 표시

CI — 내부 링크 검사

저장소 루트에서:

pnpm --filter docs run check:graph

풀리지 않은 내부 링크가 하나라도 있으면 종료 코드 1로 실패합니다. GitHub Actions CI에도 동일 단계가 포함되어 있습니다.

설정

  • site (barodoc.config.json) — https:// 링크가 같은 사이트인지 판별할 때 사용합니다.
  • i18n — 로케일 폴더 구조가 위키/상대 경로 해석에 영향을 줍니다.

경로와 check:graph

  • 기본 로케일(영어) URL에는 로케일 세그먼트가 없습니다. 파일은 src/content/docs/en/… 이지만 공개 경로는 /docs/guides/… 형태입니다.
  • /ko/docs/…와 /docs/ko/… — 그래프 해석 시 같은 문서로 맞춥니다. 새 링크는 /docs/ko/… 를 쓰면 됩니다.
  • 문서가 아닌 라우트(/yaml-landing-demo, /pricing 등)는 인덱스에 없어도 broken으로 잡지 않습니다. docs, help 등 콘텐츠 섹션 아래 경로만 검사합니다.
  • 인라인 코드(백틱) 안의 [[…]]·링크는 스캔에서 제외합니다.