문서 · Astro 정책

원본 다운로드: Markdown · PDF

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

원칙

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

docs-site/public/downloads/에 Markdown + PDF 저장
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 생성

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

Astro 사이트

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는 알려진 손상 패턴을 검사한 뒤 웹 페이지를 생성합니다.