웹 공개 가이드

이 문서는 현재 위키를 MkDocs + Material for MkDocs + Vercel Hobby 기준으로 웹에 배포하는 절차를 정리합니다. OCI에서 직접 정적 파일을 서빙하려면 oci-static-hosting.md를 따릅니다.

목적

• 현재 저장소 구조를 크게 바꾸지 않고 정적 사이트를 만든다.
• 홈은 ../index.md를 유지한다.
• wiki/는 지식 문서층, docs/는 운영 문서층으로 노출한다.
• raw/imports/ 아래 보관본은 웹 빌드에서 제외하고, repo-local 보관본으로만 유지한다.

로컬 준비

의존성 설치:

python3 -m pip install -r requirements.txt

로컬 미리보기

개발 서버:

python3 scripts/stage_mkdocs_docs.py
python3 -m mkdocs serve

브라우저에서 http://127.0.0.1:8000을 열어 홈, 도메인 허브, 운영 문서 링크가 이어지는지 확인합니다.

정적 빌드

정적 산출물 생성:

python3 scripts/stage_mkdocs_docs.py
python3 -m mkdocs build

성공하면 site/ 디렉터리가 생성됩니다.

보조 명령:

make web-build
make web-serve

Vercel 연결

Vercel 프로젝트는 아래 값으로 연결합니다.

• Repository: bluecafe/wiki
• Framework Preset: Other
• Install Command: python3 -m pip install --break-system-packages -r requirements.txt
• Build Command: python3 scripts/stage_mkdocs_docs.py && python3 -m mkdocs build
• Output Directory: site
• Production Branch: main

루트의 vercel.json이 같은 값을 다시 고정합니다.

배포 전 점검

• make verify가 통과하는지 확인
• mkdocs build가 오류 없이 끝나는지 확인
• 홈이 ../index.md 기준으로 렌더링되는지 확인
• ../wiki/domain-ai-nornen.md, ../wiki/domain-chemical.md, ../wiki/domain-claude-forge.md, ../wiki/domain-timebooks.md 링크가 정상적으로 열리는지 확인
• README.md와 주요 운영 문서가 메뉴에서 보이는지 확인
• raw/imports/ 문서가 메뉴에 직접 나타나지 않는지 확인

운영 원칙

• 새 문서를 추가해도 웹 탐색 경로는 기본적으로 ../index.md와 도메인 허브에서 시작한다.
• 사이트 메뉴는 mkdocs.yml의 명시적 nav를 우선한다.
• mkdocs.yml은 .mkdocs-docs/ staging 디렉터리를 실제 docs_dir로 사용한다.
• staging 스크립트는 raw/imports/를 복사하지 않으므로, source 문서 본문에서는 raw 보관본을 웹 링크 대신 repo-local 경로 안내로 표기한다.
• Vercel 빌드 환경에서는 Python이 uv로 관리될 수 있으므로 install command에 --break-system-packages를 포함한다.
• 링크 경로가 바뀌거나 웹 빌드가 깨지면 콘텐츠 변경과 같은 단위에서 함께 수정한다.
• 기존 GitHub Actions /.github/workflows/verify.yml은 콘텐츠 검증 전용으로 유지하고, 웹 배포는 Vercel이 맡는다.

MkDocs 경고 정책

• The following pages exist in the docs directory, but are not included in the "nav" configuration 경고는 현재 저장소에서 기본적으로 허용합니다.
• 이유: 이 저장소는 index.md, wiki/domain-*.md, docs/README.md를 중심 허브로 쓰고 모든 문서를 메뉴에 직접 노출하지 않습니다.
• 즉시 수정이 필요한 경고는 아래 둘뿐입니다.
• 실제 링크 해석 실패나 빌드 실패를 일으키는 경고
• 의도와 달리 웹에 노출되면 안 되는 문서가 staging 경로에 포함된 경우
• 단순 not in nav 경고만으로는 실패로 보지 않습니다.
• 다만 새 문서가 허브 어디에서도 도달되지 않는다면 웹 정책 문제가 아니라 위키 구조 문제이므로 index.md, 도메인 허브, source 연결을 먼저 보강합니다.

배포 URL 확인

• https://wiki-<hash>-bluecafe-7553s-projects.vercel.app 형태의 URL은 특정 시점 배포에 고정됩니다. 예전 배포 URL에는 최신 수정이 보이지 않을 수 있습니다.
• 최신 상태 확인은 alias URL을 기준으로 합니다.
• https://wiki-bluecafe-7553s-projects.vercel.app
• https://wiki-git-main-bluecafe-7553s-projects.vercel.app
• 커스텀 alias가 붙어 있으면 그 URL
• 배포 상태가 헷갈리면 vercel ls wiki로 최신 production URL을 확인하고, 필요하면 vercel inspect <deployment-url>로 alias를 다시 확인합니다.