# 문서·Astro 사이트 정책 (LivekitDev)

> 작성일: 2026-07-19  
> 적용: 이 프로젝트 및 (전역 규칙에 따라) 유사 문서화 작업

## 원칙

분석, 설계, 아키텍처, 런북, 실험 결과 정리 등 **지식을 남기는 작업** 후에는 항상:

1. **`docs-site/public/downloads/`에 Markdown + PDF** 저장
2. **`docs-site/` Astro Starlight에 페이지 추가/갱신**

한쪽만 갱신하지 않습니다.

## 체크리스트

- [ ] `docs-site/public/downloads/<kebab-name>.md` 작성 또는 수정
- [ ] `docs-site/public/downloads/<kebab-name>.pdf` 생성/재생성
- [ ] `docs-site/src/content/docs/` 에 동일 주제 페이지 반영
- [ ] 필요 시 `docs-site/astro.config.mjs` 사이드바 항목 갱신
- [ ] 사용자 응답에 **MD / PDF / Astro 경로** 안내

## PDF 생성

```powershell
uv run --with fpdf2 scripts/md_to_pdf.py docs-site/public/downloads/<name>.md docs-site/public/downloads/<name>.pdf
```

## Astro 사이트

```powershell
cd docs-site
npm install   # 최초 1회
npm run dev   # http://localhost:4321
npm run build
```

### 콘텐츠 위치

- 원본(아카이브·PDF 포함): `docs-site/public/downloads/*.md`
- 웹 표시용: `docs-site/src/content/docs/**/*.md` (Starlight frontmatter 포함)

웹 페이지에는 Starlight용 frontmatter(`title`, `description`)를 붙입니다.  
본문은 `docs-site/public/downloads/` 원본과 동기화합니다.

## 파일 명명

- kebab-case: `project-analysis.md`, `getting-started.md`
- 같은 stem으로 PDF: `project-analysis.pdf`

## 전역 규칙

Grok / Claude 전역 지침에도 동일 정책이 등록되어 있습니다.

- `C:\Users\Administrator\.grok\Agents.md`
- `C:\Users\Administrator\.claude\Claude.md`
- 프로젝트: `AGENTS.md`

## 문자 인코딩

모든 Markdown은 UTF-8로 저장합니다. 깨진 문자가 저장된 파일은 인코딩 선언만 바꿔도 복구되지 않습니다. `npm run sync:docs`는 알려진 손상 패턴을 검사한 뒤 웹 페이지를 생성합니다.