0022. 문서 사이트는 이 저장소의 site/에 Starlight로 두고 Cloudflare로 docs.belloga.com에 올린다

This content is not available in your language yet.

맥락

처음 보는 사람이 Belloga를 이해하고 설치까지 갈 수 있는 공개 페이지가 없다. README는 저장소를 연 사람에게만 보이고, 설치 안내는 gh 명령뿐이다. 결정 기록(ADR)도 저장소 안에서만 읽힌다.

사이트에 담을 내용은 소개, 설치, 기능, 결정 기록이다. 한국어와 영어로 낸다. 서버의 동기화 설계 설명도 뒤이어 들어갈 예정이다. 서버 저장소는 공개하지 않으므로 사이트가 그 설계를 보여 줄 공개 창구가 된다.

사이트는 이 저장소의 site/에 앱과 따로 설치하고 빌드하는 패키지로 둔다.
정적 문서 생성기로 Astro Starlight를 쓴다. 페이지는 마크다운으로 쓰고, 한국어를 기본 언어(/), 영어를 /en/에 둔다.
결정 기록은 docs/decisions/의 원본을 빌드 때 사이트 문서로 바꿔 낸다. 사이트 쪽에 복사본을 커밋하지 않는다.
Cloudflare에 저장소를 연결해 main에 반영될 때 정적 자산으로 배포하고, docs.belloga.com에 연결한다.

서버 저장소의 모노레포에 두기: 앞으로 만들 관리용 웹 앱과 함께 두는 안이었다. 그러나 사이트 내용(소개, 설치, 기능, 결정 기록)은 앱과 함께 바뀌므로, 같은 저장소에 있어야 기능을 바꾸는 PR에서 문서도 함께 고친다. 사이트는 공개해도 숨길 것이 없다. 기각.
HTML과 CSS로 직접 만들기: 빌드 단계와 의존성이 없다는 장점이 있다. 하지만 결정 기록 마크다운을 HTML로 바꾸는 변환기, 두 언어 페이지의 공통 레이아웃, 사이드바와 검색을 직접 만들어야 한다. 기각.
VitePress: 같은 일을 할 수 있다. Starlight는 번역이 없는 페이지를 기본 언어 원본으로 보여 주는 동작이 내장되어 있어, 결정 기록을 한국어 원본으로만 두는 방침과 맞는다.
Next.js: 사이트가 정적 문서뿐이라 서버 렌더링과 API 라우트를 쓸 데가 없다. 기각.
GitHub Pages: 무료로 쓸 수 있다. 그러나 belloga.com 존이 이미 Cloudflare에 있고 서버의 도메인도 거기서 관리하므로, 도메인과 배포를 한곳에 모으려고 Cloudflare를 쓴다.

설치 파일 이름에서 버전을 뺐다(Belloga-Setup.exe, Belloga-arm64.dmg). 그래야 사이트가 releases/latest/download/ 고정 링크를 쓸 수 있다.
문서만 바꿔 main에 반영해도 릴리스 워크플로가 실패하지 않도록, 같은 버전의 태그가 있으면 릴리스를 건너뛴다. 대신 버전을 올리지 않은 실수는 실패가 아니라 알림으로만 드러난다.
PR CI에서 사이트도 빌드해, 결정 기록의 깨진 링크 같은 문제를 병합 전에 잡는다.
결정 기록의 영어 번역은 하지 않는다. 영어 사이트에서는 한국어 원본에 안내 문구가 붙어 보인다.