문서 스타일 가이드¶

docs/ko/의 한국어 문서를 새로 쓰거나 영어 문서와 맞출 때 적용하는 규약입니다. 맞춤법 교정보다 문서 전체의 일관성을 유지하는 데 목적이 있습니다.

문서 유형은 기술 문서입니다. 명령·경로·포트·코드블록·표 중심이며 어조는 격식체를 유지하되 도구·프로토콜 이름은 영어 표기를 그대로 둡니다.

1. 어조와 격식¶

• 본문 서술은 합쇼체(~합니다 / ~습니다) 로 씁니다.
• 짧은 라벨 목록(책임·구성 요소·결과 등)은 개조식(명사 또는 ~음 종결)을 허용합니다. 단, 한 목록 안에서는 한 가지 방식으로 통일합니다.
• 절차·설명 목록은 완전한 합쇼체 문장으로 씁니다.

[좋음] 외부 트래픽은 yggdrasil의 Caddy가 tailnet으로 전달합니다. (서술 → 합쇼체)
[좋음] - Forgejo (Git 호스팅) 운영                              (라벨 목록 → 개조식)
[나쁨] 설정은 zensical.toml을 사용한다.                         (한다체 혼용 금지)

2. 용어¶

도구·프로토콜·명령과 직결되는 용어는 영문 표기를 그대로 씁니다(음차 금지). 일반어는 한글로 통일합니다.

조사는 영어 표기에 바로 붙입니다: tailnet에, flake를, PR을.

3. 숫자와 단위¶

• 본문의 용량·수치는 숫자 + 공백 + 단위: 4 GB, 512 MB.
• 설정 리터럴(512M, 15d, 3m 등)은 원형을 유지하며 가능하면 인라인 코드로 감쌉니다.

4. 목록과 구조¶

• 불릿은 -, 순서가 있는 단계는 1. 2., 할 일은 - [ ] 체크리스트.
• 코드블록은 언어 태그를 명시합니다: ```bash, ```nix, ```text.
• 모든 페이지는 파일 맨 위에 네비게이션 아이콘 front matter를 둡니다.

---
icon: fontawesome/solid/<이름>
---

5. 인용과 강조¶

• 식별자·경로·포트·명령·파일명 → 인라인 코드.
• 경고·필수 조건 강조 → 굵게.
• 개념이나 직접 인용 문구 → 큰따옴표 "".
• 안내 상자는 admonition을 씁니다: !!! note, !!! tip, !!! warning, !!! danger.

6. 날짜¶

• 구조적 메타데이터(상태·날짜 필드)는 ISO 형식 YYYY-MM-DD (예: 2026-06-12).
• 본문 산문은 한글 형식 YYYY년 M월 (필요하면 "현재"를 덧붙임).

7. 링크¶

• 내부 링크는 상대 경로 인라인 링크로 씁니다: [보안 모델](security.md), [설계 원칙](../principles.md).
• 빌드가 zensical build --strict라서 깨진 내부 링크는 빌드 실패가 됩니다. 새 페이지는 nav에도 등록합니다(문서 사이트 참고).

빠른 체크리스트¶

• 서술은 합쇼체, 라벨 목록은 개조식(목록 내 통일)
• tailnet·flake·PR 등 기술어는 영어 표기 (음차 금지)
• 일반어는 저장소·워크플로·디렉토리로 통일
• 용량/수치는 4 GB처럼 숫자 + 공백 + 단위
• 코드블록에 언어 태그, 페이지에 아이콘 front matter
• 식별자는 인라인 코드, 강조는 굵게, 안내는 !!! admonition
• 날짜는 필드 ISO / 본문 한글
• 내부 링크 유효성 확인 + 새 페이지는 nav 등록