Markdown 규약
Markdown 방언, 헤딩 구조, 코드 펜스 선언, 내부 링크 형식, 작성자 헤더, 검증기 강제를 표준화합니다.
직접 작성하는 모든
.md및.mdx아티팩트에 걸친 Markdown 형태와 서식의 표준 참조.CLAUDE.md의 Conventions 요약은 인라인 선언이고, 이 페이지는 다운스트림 기여자가 인용하는 독립형 참조입니다.
1. 방언
GitHub-Flavored Markdown(GFM)이 호스트 방언입니다. 모든 아티팩트는 GitHub 웹 UI, Fumadocs 문서 사이트, 일반적인 Markdown 지원 편집기에서 올바르게 렌더링됩니다.
2. 헤딩 계층
파일당 H1은 하나입니다. 이후의 헤딩은 수준을 건너뛰지 않고 단조롭게 내려갑니다(H2 → H3 → H4). 헤딩은 문장형 대소문자 표기를 따르며, ALL-CAPS도, Title Case Across Every Word도 쓰지 않습니다. H1은 문서의 주 제목을 담습니다. 문서 사이트 페이지에서는 프런트매터의 title이 H1으로 렌더링되고 문서 사이트 내비게이션에서 해당 페이지의 앵커가 되므로, 페이지 본문은 H2에서 시작합니다.
3. 코드 블록
펜스 코드 블록은 언어를 선언합니다(```python, ```bash, ```yaml, ```json, ```mermaid). 태그가 없는 블록은 구문 강조를 막고 작성 드리프트의 신호가 됩니다. .markdownlint.json에 구성된 markdownlint MD040 규칙이 언어 태그를 강제합니다.
4. 내부 링크
내부 상호 참조는 사이트 루트 경로를 사용합니다(예: [Authorship header](/docs/reference/authorship-header)). .md/.mdx 확장자가 붙은 단순 저장소 상대 경로(/docs/foo.md)와 같은 저장소를 가리키는 전체 URL(https://github.com/ahmed-g-gad/apothem/blob/main/...)은 페이지 이름 변경과 섹션 재구성에 걸림돌이 되므로 사이트 내 링크에는 쓰지 않습니다.
이러한 /docs/... 사이트 루트 경로 — 그리고 기본값이 아닌 코호트 로케일을 위한 /<locale>/docs/... 형식 — 는 link-check 검증기가 site/content/docs/ 아래 디스크상의 페이지 집합을 기준으로 해석합니다. /docs/a/b는 site/content/docs/a/b.mdx 또는 폴더 인덱스 site/content/docs/a/b/index.mdx에 대응하고, 로케일 형식은 site/content/docs/<locale>/ 하위 트리 아래에 대응합니다. 삭제되거나 이름이 바뀐 라우트로 가는 링크는 어느 파일로도 해석되지 않으며, 권고성 매처인 link-check가 이를 죽은 라우트(사용자에게 보이는 404)로 보고합니다. 이 매처는 실행을 실패시키지 않습니다(§6 참조).
변경 가능한 ref(main, master, latest, HEAD)를 가리키는 외부 링크는 링크된 콘텐츠의 안정성이 중요할 때마다 커밋 SHA나 릴리스 태그로 고정합니다. 변동성 있는 참조는 인접한 {/* volatile */} 주석으로 그러함을 문서화합니다.
5. 작성자 헤더
모든 Markdown 아티팩트(src/apothem/schemas/header-exceptions.txt에 열거된 예외 제외)는 작성자 헤더에 따라 파일 형식에 맞는 주석 변형으로 된 표준 작성자 헤더, 즉 SPDX-License-Identifier: MIT 한 줄을 둡니다. .md 파일에서는 HTML 주석, .mdx 파일에서는 {/* ... */} 주석입니다. 프런트매터가 없으면 헤더 줄이 1번째 줄입니다. YAML 프런트매터가 있으면 프런트매터가 바이트 0에 남고, 헤더 줄은 닫는 --- 뒤에 옵니다.
6. 검증기
.pre-commit-config.yaml의 pre-commit markdownlint 훅은 .markdownlint.json의 규칙 정책으로 markdownlint-cli를 실행하며, §§1–4 규칙의 대부분을 강제합니다. Markdown Lint 워크플로는 main에 대한 모든 푸시와 Markdown을 변경하는 모든 풀 리퀘스트에서 같은 훅을 CI에서 실행합니다. 따라서 CI는 훅이 고정한 버전으로 린트합니다. 정책은 MD013(줄 길이), MD033(인라인 HTML), MD041(첫 줄 헤딩)을 끕니다. 또한 MD038도 끄는데, 표준 옵션 레이블 접미사 (Recommended)가 코드 스팬 안에서 앞쪽 공백을 유지하기 때문입니다. MD060도 끄는데, 코퍼스가 사용하는 촘촘한 |---| 구분 행을 가진 압축 셀 표를 받아들이는 표 열 스타일이 없기 때문입니다. MD024는 형제 헤딩만 검사하므로, 각 릴리스가 CHANGELOG.md에서 반복하는 Added, Changed, Fixed, Security 헤딩은 통과합니다. 각 선택의 이유는 훅 옆에 적혀 있습니다. 훅은 테스트가 바이트를 정하는 테스트 픽스처 트리 tests/fixtures/, tests/conformity/, tests/conformity-scenarios/fixtures/, tests/scripts/inject-header/fixtures/를 건너뜁니다. 또한 plugins/claude-code/도 건너뜁니다. 이 트리는 python scripts/dev/assemble_plugin_tree.py가 src/apothem/에서 생성합니다. 명령의 번호가 매겨진 단계가 각각 별도 파일이 되므로, 단계 파일의 목록은 해당 단계 번호에서 시작합니다. src/apothem/ 소스는 린트 대상이므로, 플러그인 콘텐츠의 발견 사항은 그곳에서 고치고 플러그인 트리를 다시 생성합니다.
src/apothem/conformity/file_header_grep.py의 file-header-grep은 §5를 검사합니다. src/apothem/conformity/link_check.py의 link-check 검증기는 §4의 링크 해석 규율을 검사합니다 — 상대 링크는 소스 파일의 디렉터리를 기준으로, /docs/...(및 /<locale>/docs/...) 사이트 라우트는 site/content/docs/ 페이지 집합을 기준으로 해석하며, 디스크상의 어떤 페이지로도 해석되지 않는 링크를 표시합니다. 둘 다 Write 단위의 권고성 매처입니다. 이들은 pre-commit conformity-corpus-perwrite 훅과 .github/workflows/conformity.yml에 있는 Conformity 워크플로의 corpus-perwrite-gate 작업에서 실행되며, 두 곳 모두에서 실행을 실패시키지 않고 발견 사항을 보고합니다. .github/workflows/ci.yml에 있는 CI 품질 작업의 python -m apothem.conformity.gate --all . --strict는 독립형 검증기만 다루므로, 둘 중 어느 것도 실행하지 않습니다.