hook-docs — documentar um hook ao estilo ReactUse
A documentação fica no site Astro packages/website-astro. A barra lateral e as rotas são construídas
automaticamente a partir dos caminhos dos arquivos — não há routes.json ou configuração de barra lateral para editar.
Locais dos arquivos (um por idioma)
packages/website-astro/src/content/docs/{categoria}/useX.mdx # Inglês
packages/website-astro/src/content/docs-zh-hans/{categoria}/useX.mdx # 简体中文
packages/website-astro/src/content/docs-zh-hant/{categoria}/useX.mdx # 繁體中文
{categoria} é um dos: browser, effect, element, state, integrations. A pasta que você
escolhe é a categoria — ela define a entrada do registro e a URL canônica
(https://reactuse.com/{categoria}/usex/, em minúsculas).
Frontmatter
O schema está em packages/website-astro/src/content.config.ts — apenas title é obrigatório;
description, sidebar_label, sidebar_position são opcionais. Siga o estilo existente:
---
title: useX – Exemplos e Uso de State Hook
sidebar_label: useX
description: "useX é um hook React que … (uma frase, usada como meta description)."
---
Estrutura do corpo
Siga a forma estabelecida (veja content/docs/browser/useClipboard.mdx):
# useX
Resumo de uma linha sobre o que ele faz.
Um parágrafo curto explicando o hook, com link para a página MDN/especificação relevante quando útil.
### Quando Usar
- bullet de um caso de uso concreto
- outro
### Notas
- segurança SSR / limitações de suporte do navegador
- quaisquer pegadinhas
## Uso
```tsx live
function Demo() {
const [valor, definir] = useX(0);
return <button onClick={() => definir(valor + 1)}>{valor}</button>;
};
%%API%%
- O bloco ` ```tsx live ` renderiza uma demonstração ao vivo e editável. Escreva a demonstração **embutida** — ela não
é importada do código-fonte do hook.
- Mantenha `%%API%%` como a última linha. Ela é substituída durante a construção pela tabela de API gerada
(a partir do JSDoc do `interface.ts` do hook); se ainda não houver documentação de API, ela é removida silenciosamente.
## Traduções
Os arquivos zh-Hans / zh-Hant espelham exatamente a estrutura em inglês — traduza o texto e
os campos `title`/`description` do frontmatter, mantendo a demonstração de código idêntica.
zh-Hans → zh-Hant não é uma simples conversão de caracteres; estes termos diferem:
| 简体 | 繁體 | | 简体 | 繁體 |
|------|------|-----|------|------|
| 状态 | 狀態 | | 默认 | 預設 |
| 函数 | 函數 | | 设置 | 設定 |
| 参数 | 參數 | | 获取 | 獲取 |
| 组件 | 組件 | | 监听 | 監聽 |
| 类型 | 類型 | | 处理 | 處理 |
| 数组 | 數組 | | 实例 | 實例 |
| 对象 | 對象 | | 管理 / 配置 | inalterado |
## Após escrever — regenerar o registro
```bash
bash scripts/generate-hook-registry.sh
Isso percorre a pasta de documentação em inglês e reescreve scripts/hook-registry.json
(nomeDoHook → { categoria, url }). Necessário para que links de blog/documentos sejam resolvidos corretamente. Verifique se o
novo hook aparece com a categoria correta e uma URL em minúsculas.