childrentime/reactuse

hook-docs — 以 ReactUse 風格撰寫 Hook 文件

文件位於 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/，小寫）。

Frontmatter

Schema 定義在 packages/website-astro/src/content.config.ts — 只有 title 是必需的；description、sidebar_label、sidebar_position 為可選。請比照現有風格：

---
title: useX – State Hook 使用方式與範例
sidebar_label: useX
description: "useX 是一個 React Hook，用於……（一句話，作為 meta description）。"
---

主體結構

遵循既有的格式（請參考 content/docs/browser/useClipboard.mdx）：

# useX

一行總結其功能。

一段簡短說明，介紹此 Hook。如有需要可連結至相關的 MDN/spec 頁面。

### 使用時機

- 具體使用案例的項目符號
- 另一個案例

### 備註

- SSR 安全性 / 瀏覽器支援限制
- 任何注意事項

## 使用方式

```tsx live
function Demo() {
  const [value, set] = useX(0);
  return <button onClick={() => set(value + 1)}>{value}</button>;
};

%%API%%

- ` ```tsx live ` 程式碼區塊會呈現一個可即時編輯的示範。請**內聯**撰寫示範 — 它不會從 Hook 的原始碼匯入。
- 請將 `%%API%%` 保留為最後一行。建置時它會被替換為產生的 API 表格（來自 Hook 的 `interface.ts` JSDoc）；如果尚無 API 文件，則會自動移除。

## 翻譯

簡體中文 / 繁體中文檔案需完全鏡像英文的結構 — 翻譯 prose 以及 frontmatter 的 `title`/`description`，程式碼示範保持相同。

簡體中文 → 繁體中文並非純字元轉換；以下詞彙有差異：

| 簡體 | 繁體 |     | 簡體 | 繁體 |
|------|------|-----|------|------|
| 状态 | 狀態 |     | 默认 | 預設 |
| 函数 | 函數 |     | 设置 | 設定 |
| 参数 | 參數 |     | 获取 | 獲取 |
| 组件 | 組件 |     | 监听 | 監聽 |
| 类型 | 類型 |     | 处理 | 處理 |
| 数组 | 數組 |     | 实例 | 實例 |
| 对象 | 對象 |     | 管理 / 配置 | 不變 |

## 寫入後 — 重新產生註冊檔

```bash
bash scripts/generate-hook-registry.sh

此腳本會遍歷英文文件資料夾，重新寫入 scripts/hook-registry.json（hookName → { category, url }）。這是必要的，以便部落格/文件連結能正確解析。請確認新 Hook 出現在正確的分類中，且 URL 為小寫。