문서 작성 규칙

문서 하나를 더할 때 손이 가는 곳은 세 군데입니다. 마크다운 파일 두 개(한국어, 영어)와, 새 묶음을 만드는 경우 사이드바 설정입니다.

파일은 어디에 두나

wiki/src/content/docs/
├── ko/
│   ├── index.mdx          → /ko/
│   ├── about.md           → /ko/about/
│   └── deploy/cloudflare.md → /ko/deploy/cloudflare/
└── en/
    └── (같은 구조)

두 언어의 경로가 정확히 같아야 합니다. ko/deploy/cloudflare.md 를 만들었으면 영어는 en/deploy/cloudflare.md 입니다. 이름이 어긋나면 언어 전환 버튼이 그 문서를 찾지 못하고 첫 화면으로 떨어뜨립니다.

파일 이름은 소문자에 하이픈으로 씁니다. 한글 파일 이름은 쓰지 않습니다 — 주소에 그대로 나가고, 인코딩된 주소는 공유하기 나쁩니다.

프런트매터

---
title: 문서 작성 규칙
description: 문서를 더할 때 지키는 것들. 파일 위치, 프런트매터, 두 언어를 맞추는 방법.
---

title 은 그대로 <h1> 이자 사이드바 항목이고, description 은 검색결과와 미리보기에 나가는 문장입니다. description 은 선택이 아니라 필수로 씁니다. 없으면 검색 결과에 본문 첫 줄이 잘려 나가는데, 대개 문맥이 없는 문장이라 클릭할 이유를 주지 못합니다.

title 은 짧게, description 은 한두 문장으로 씁니다. 한글은 라틴 문자보다 글자당 폭이 약 두 배라 같은 글자 수라도 검색 결과에서 먼저 잘립니다. 한글 description 은 70자 근처에서 멈추는 편이 안전합니다.

사이드바에 올리기

wiki/astro.config.mjs 의 sidebar 배열이 목록의 전부입니다. 문서를 새로 만들어도 여기 없으면 목록에 나타나지 않습니다(주소로는 열립니다).

기존 묶음에 한 장 더할 때:

{ label: '배포', translations: { en: 'Deploy' }, slug: 'deploy/cloudflare' },

slug 에는 언어 부분을 빼고 씁니다. ko/ 와 en/ 양쪽에 자동으로 붙습니다.

문서가 여러 장 쌓일 묶음이면 하나씩 적는 대신 폴더를 통째로 맡기는 편이 낫습니다.

{
  label: '배포',
  translations: { en: 'Deploy' },
  items: [{ autogenerate: { directory: 'deploy' } }],
}

이렇게 두면 deploy/ 안에 파일을 놓기만 해도 목록에 올라옵니다. 순서는 프런트매터의 sidebar.order 로 잡습니다.

autogenerate 는 반드시 items 배열 안에 넣습니다. 묶음에 label 과 autogenerate 를 나란히 두는 축약형은 Starlight 0.39 에서 없어졌고, 지금은 빌드가 서지 않습니다.

본문 규칙

결론을 먼저 씁니다. 배경 설명으로 시작하면 다시 읽을 때 필요한 줄을 찾느라 스크롤합니다.
제목은 ## 부터 씁니다. # 은 프런트매터의 title 이 이미 차지했습니다.
링크에는 언어 접두어를 붙입니다. /ko/about/ 이지 /about/ 이 아닙니다. 끝의 빗금도 같이 씁니다.
명령과 경로는 백틱으로 감쌉니다. 붙여넣을 수 있는 것과 읽는 문장을 눈으로 갈라 놓습니다.
날짜는 절대값으로 씁니다. “지난달”이 아니라 2026-09-03 입니다. 위키는 몇 년 뒤에 읽힙니다.

강조 상자가 필요하면 Starlight 의 것을 씁니다.

:::caution
운영 데이터베이스를 가리킨 채로 실행하면 스키마가 밀립니다.
:::

note, tip, caution, danger 네 가지가 있습니다.

적지 않는 것

이 위키는 공개이고 검색엔진이 들어옵니다.

API 키, 토큰, 비밀번호, 접속 주소, 내부 IP — 값은 적지 않고 이름만 적습니다.
허락받지 않은 클라이언트 이름과 그쪽 내부 사정
개인을 특정하는 정보

지우면 된다고 생각하기 쉽지만, 공개된 순간 캐시와 색인에 남습니다. 커밋하기 전에 한 번 봅니다.

배포

cd wiki
npm run build          # 밀기 전에 빌드가 깨지지 않는지 확인
git push               # Cloudflare Pages 가 이 push 를 받아 빌드한다
npm run deploy:verify  # 새 빌드가 실제로 올라왔는지 확인

git push 는 배포의 시작입니다. Pages 빌드가 끝나야 반영되고, 빌드는 실패할 수 있습니다. deploy:verify 가 0으로 끝나야 배포가 끝난 것입니다.