Writing

Overview

---
name: Guide
label: 사용 안내
group: Guide
order: 10
---

문서의 범위와 핵심.

## Overview

::part[Setup]

## Installation

### Requirements

문서 폴더에는 Markdown과 선택 설정 파일. 루트 README.md는 홈(/)으로 표시하고 문서 목록에서는 제외. 루트 AGENTS.md·CLAUDE.md는 작성 지침으로 보고 문서 수집에서 제외. 이 세 파일의 이름은 대소문자를 구분하지 않음. 하위 폴더의 같은 이름은 일반 문서로 처리하므로 frontmatter 필수. node_modules, dist는 읽지 않음. 하위 폴더도 지원. .mdx는 Markdown으로 처리 · JSX 실행 미지원.

Home page

문서 폴더의 README.md가 기본 홈. 파일 이름의 대소문자는 구분하지 않음. frontmatter 없이 # 제목부터 일반 Markdown으로 작성. 제목·목차·코드 강조는 문서와 같은 처리 과정. README가 없으면 추가 안내를 표시. 사이드바의 사이트 이름을 누르면 홈으로 이동.

# My library

라이브러리 소개.

## Getting started

[설치 안내](commands.md)

하위 폴더의 README는 일반 문서로 처리하며 frontmatter 필수. 홈 템플릿을 선택하는 별도 설정은 아직 없음. 이 저장소 자체의 문서 홈은 최상위 README와 동기화. 최상위 README.md 수정 후 pnpm sync:readme 실행. 저장소의 pnpm dev·pnpm build도 시작할 때 동기화하며, 패키지를 쓰는 다른 프로젝트의 README에는 관여하지 않음.

Frontmatter

같은 첫 글자로 시작하는 이름도 허용. API와 Architecture는 각각 별도 문서. blueprint 전용 표현은 아직 미구현. 파일 경로는 확장자를 뺀 소문자 id로 사용. .md와 .mdx, 대소문자만 다른 경로의 id 중복 금지. YAML 영역은 remark-frontmatter, 값은 yaml, 필드 검증은 Zod로 처리. 빈 경로와 예약 문자 #, ?, %, *, :, \는 사용 불가. 첫 경로 /_fh/는 패키지 자원 전용. .·..·index.html 경로 조각, 제어문자, 첫 경로 /favicon.svg/는 정적 출력과 충돌하므로 사용 불가.

Navigation groups

하위 폴더를 만들지 않아도 group으로 문서를 묶음. 묶음은 페이지가 아닌 탐색 제목. 그 안의 각 문서는 독립적인 파일·URL·목차를 가짐.

묶음 순서는 Settings의 navigation. 묶음 안은 작은 order 먼저. order를 생략한 문서는 순서를 지정한 문서 뒤에서 제목순, 제목도 같으면 파일 id순. 파일 이름에 번호나 알파벳을 붙여 순서를 맞출 필요 없음. 모든 문서 묶음은 항상 표시. 문서는 이름과 1px 트리 선으로 표시. Contents는 현재 문서 안의 절만 표시.

Sections and parts

• ## → section · Contents의 상위 항목
• ### → subsection · 해당 section 아래 중첩 항목
• 첫 section 앞의 글 → 문서 header
• ::part[Setup] → 여러 section을 묶는 part · TOC 그룹
• 제목 id → GitHub 방식 · 같은 제목은 -1, -2 접미사

제목과 Contents에는 자동 번호를 붙이지 않음. 번호가 필요하면 ## 01. Setup처럼 제목에 직접 작성.

Links

[Settings](settings.md)
[Settings with query](settings.md?view=compact#navigation)
[Status badges](settings.md#status-badges)
[Home](README.md)

상대 Markdown 링크 → 사이트 문서 URL. GitHub에서도 같은 파일로 이동. 루트 README 링크는 /로 변환. 하위 문서의 ../README.md#start도 /#start로 변환. 외부 URL, 절대 URL, 같은 문서의 hash는 원문 유지. 앵커로 이동한 제목은 약 3초 동안 형광색으로 강조한 뒤 서서히 해제. 같은 앵커를 다시 누르면 강조 시간을 다시 시작. 접힌 Details의 제목도 펼친 뒤 표시. 움직임 감소 설정에서는 전환 효과 없이 강조만 표시·해제.

Flowcharts

```mermaid
flowchart LR
    a("작성") --> b("확인")
    b --> c("배포")
```

빌드 시 격자 SVG 생성. 짧은 노드 이름, 한 단어 선 라벨 권장. 긴 라벨은 <br>로 분리.

Content features

상태 문구는 Settings에서 변경. 원시 HTML은 그대로 반영되는 작성 형식. 외부 콘텐츠의 실행·격리 환경은 제공하지 않음.

Block components

:::note[Scope]
보충 설명과 제약.
:::

:::details[Implementation]
### Response contract

필요할 때 펼쳐 보는 구현 상세.
:::

• Note: 항상 표시되는 보충 설명 · 제목·본문 필수 · 속성 없음
• Details: 기본 접힘 · 제목·본문 필수 · {open}으로 기본 펼침
• 속성의 값 표기·중복 open, 주석·빈 코드·빈 목록만 있는 본문은 오류
• 제목: 일반 텍스트 · 링크·강조·인라인 코드 미지원
• 본문: 일반 Markdown · ### 이하 제목과 Note·Details 중첩
• 문서 구획: ##와 ::part는 부품 밖
• 닫는 fence: 필수 · 중첩하거나 코드에 :::가 있으면 바깥 fence를 더 길게 작성
• 부품 내부 제목: TOC·hash 지원 · hash 이동 시 상위 Details 공개
• 미지원 형태·속성·빈 입력: 빌드 오류 · Errors

Decision·Question·API reference는 section·표·링크로 작성. 전용 부품의 필요성은 실제 샘플을 기준으로 판단.

Writing conventions

• 한 줄 한 사실
• 제목과 요약은 명사구 중심
• 경위보다 현재 계약·결정·제약
• 식별자와 값은 코드, 절차는 목록, 비교는 표
• 실제 지원 범위와 미구현 범위 구분

Language

• 독자: 한국어 사용자 · 기본적인 영어와 개발 용어 이해 가능
• 제목·내비게이션·짧은 라벨: 익숙한 영어 표현 우선
• 본문·소개·사용법·선택 이유·오류 설명: 가능한 한 한국어
• 기술 용어·명령·코드·식별자: 원래 표기 유지 · 어색한 직역 금지
• 같은 개념은 같은 용어 사용 · 문서마다 다른 번역이나 별칭 사용 금지
• 영어 제목은 sentence case · Status badges, Writing conventions · 제품명과 API 표기는 원형 유지

name과 group은 짧은 영어 이름. label은 문서 설명이므로 한국어가 기본. 코드 예시도 같은 기준 적용: 제목은 Overview, 설명문은 한국어.

Terms