[보관] 25. Astro Starlight 위키 셋업

시각: 2026-04-28 12:00~12:08 KST

무엇이 있었나

• 사용자: “astro 셋팅해서 내부 문서들을 위키 형식으로 보고 싶어.”
• wiki/ 서브폴더에 Astro 5.18 + Starlight 0.37 + sharp 설치
• wiki/scripts/sync.mjs — 프로젝트 root + history/ + study/ 의 .md 파일을 wiki/src/content/docs/로 복사하면서 Starlight 프론트매터 자동 주입 (제목은 첫 H1에서 추출)
• wiki/astro.config.mjs — 사이드바: 개요 → 설계·셋업(01~08) → 평가 연구 → 히스토리(자동 생성)
• 빌드 결과: 45 페이지 + Pagefind 검색 인덱스
• 접속: http://localhost:4321/

왜 그렇게 갔나

• 프로젝트 마크다운을 그대로 두고 sync 스크립트로 가져오는 방식 — 원본 손상 없음, 위키는 파생물
• Starlight: Astro 공식 docs 테마라 검색·다크모드·사이드바·반응형이 기본 제공
• 시드 sync 스크립트는 매 npm run dev/build 전 자동 실행되도록 package.json scripts에 체이닝

막혔던 이슈와 해결

1. npm cache permission error — 사용자 글로벌 캐시(~/.npm)가 읽기전용 → wiki/.npmrc에 cache=/tmp/hamster-npm-cache로 우회
2. zod v4 vs v3 충돌 — Astro 5는 zod v3, @astrojs/sitemap 3.7+은 zod v4를 끌어와 hoist 충돌. overrides로 sitemap을 3.6.0에 핀.
3. Astro 6 Node 22+ 요구 — Node 20.17 환경이라 Astro 5.5 + Starlight 0.37 조합으로 다운그레이드.
4. dev 모드 라우트 404 — defaultLocale: 'ko' + locales: { ko: ... } 으로 잡으면 Starlight가 docs/ko/ 디렉토리를 기대. 단일 언어는 defaultLocale: 'root' + locales: { root: ... } 패턴으로 변경하면 content가 docs/ 루트에 그대로 있어도 라우트 생성. 이게 핵심 트랩.

무엇이 남았나

• 사용 명령:
  • cd wiki && npm run dev — 라이브 리로드 위키 (localhost:4321)
  • npm run build && npm run preview — 정적 빌드 미리보기
  • npm run sync — 새 마크다운 추가 후 콘텐츠만 다시 동기화
• wiki/src/content/docs/는 매 sync마다 비워졌다 다시 채워짐 — 직접 편집 금지 (덮어쓰기됨). 항상 프로젝트 root의 .md를 수정.
• wiki/.gitignore로 node_modules, dist, .astro, src/content/docs 모두 제외 — 위키는 빌드 산출물이라 git에 안 올림.
• 배포가 필요하면 npm run build 후 dist/를 GitHub Pages·Vercel·Netlify 등에 올리면 됨.