hook-docs — ReactUse 방식으로 훅 문서 작성하기
문서는 Astro 사이트 packages/website-astro에 위치합니다. 사이드바와 라우트는 파일 경로로부터 자동으로 생성되며, 별도로 routes.json이나 사이드바 설정을 편집할 필요가 없습니다.
파일 위치 (로캘별 하나씩)
packages/website-astro/src/content/docs/{category}/useX.mdx # 영어
packages/website-astro/src/content/docs-zh-hans/{category}/useX.mdx # 간체 중국어
packages/website-astro/src/content/docs-zh-hant/{category}/useX.mdx # 번체 중국어
{category}는 다음 중 하나입니다: browser, effect, element, state, integrations. 선택한 폴더 자체가 카테고리이며, 레지스트리 항목과 정규 URL(https://reactuse.com/{category}/usex/, 소문자)을 결정합니다.
프론트매터
스키마는 packages/website-astro/src/content.config.ts에 정의되어 있습니다. title만 필수이며, description, sidebar_label, sidebar_position은 선택 사항입니다. 기존 스타일과 일관되게 작성하세요:
---
title: useX – 상태 훅 사용법 및 예시
sidebar_label: useX
description: "useX는 ...하는 React 훅입니다. (한 문장, 메타 설명으로 사용됩니다.)"
---
본문 구조
기존 형식(content/docs/browser/useClipboard.mdx 참고)을 따릅니다:
# useX
무엇을 하는지 한 줄 요약.
훅을 설명하는 짧은 문단. 필요 시 관련 MDN/사양 페이지로 링크.
### 사용 시기
- 구체적인 사용 사례 불릿
- 또 다른 예
### 참고 사항
- SSR 안전성 / 브라우저 지원 제약
- 주의해야 할 사항
## 사용법
```tsx live
function Demo() {
const [value, set] = useX(0);
return <button onClick={() => set(value + 1)}>{value}</button>;
};
%%API%%
- ` ```tsx live ` 펜스는 라이브 편집 가능한 데모를 렌더링합니다. 데모는 **인라인**으로 작성하며, 훅 소스에서 가져오지 않습니다.
- 마지막 줄에 `%%API%%`를 유지하세요. 빌드 시 생성된 API 테이블(훅의 `interface.ts` JSDoc에서 생성)로 대체됩니다. 아직 API 문서가 없으면 자동으로 제거됩니다.
## 번역
zh-Hans / zh-Hant 파일은 영어 구조를 정확히 반영합니다. 산문과 프론트매터 `title`/`description`은 번역하고, 코드 데모는 동일하게 유지합니다.
zh-Hans → zh-Hant는 단순한 문자 변환이 아닙니다. 다음 용어들이 다릅니다:
| 간체 | 번체 | | 간체 | 번체 |
|------|------|-----|------|------|
| 状态 | 狀態 | | 默认 | 預設 |
| 函数 | 函數 | | 设置 | 設定 |
| 参数 | 參數 | | 获取 | 獲取 |
| 组件 | 組件 | | 监听 | 監聽 |
| 类型 | 類型 | | 处理 | 處理 |
| 数组 | 數組 | | 实例 | 實例 |
| 对象 | 對象 | | 管理 / 配置 | 변경 없음 |
## 작성 후 — 레지스트리 재생성
```bash
bash scripts/generate-hook-registry.sh
이 명령어는 영어 문서 폴더를 읽고 scripts/hook-registry.json을 다시 작성합니다(hookName → { category, url }). 블로그/문서 링크가 올바르게 작동하도록 하기 위해 필요합니다. 새 훅이 올바른 카테고리와 소문자 URL로 나타나는지 확인하세요.