문서 작성 규칙

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

파일은 어디에 두나

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으로 끝나야 배포가 끝난 것입니다.