timerise-ai/help-center-markdown

Central de Ajuda — artigos em Markdown, pesquisa, i18n

Uma central de ajuda é um pequeno site estático com um requisito fundamental: cada artigo deve ser acessível — pela barra lateral, pela pesquisa, de uma localidade traduzida que ainda não o possui. Escrito pelo engenheiro que entregou este módulo; a implementação anterior era uma central de ajuda de site de marketing. O módulo abaixo mantém esse requisito como propriedades verificadas: a barra lateral mostra cada artigo de cada categoria, a pesquisa classifica uma consulta independentemente de como é digitada, links relacionados resolvem ou o validador falha na construção. O carregador, a pesquisa e os conjuntos de tags cobrem cada um; o registro está em references/provenance.md.

Quando usar

Ao construir ou estender uma central de ajuda, seção de documentação ou base de conhecimento cujos artigos são arquivos Markdown no repositório, no Next.js App Router, com ou sem múltiplas localidades.

Quando NÃO usar

• Um blog. Postagens com data, autor, capas e slugs localizados são um modelo de conteúdo diferente; mantenha o módulo de blog do host.
• Documentação gerada a partir de código (OpenAPI, TypeDoc) — use seus geradores e vincule à saída.
• Um site de ajuda com CMS com editores publicando em tempo de execução — o contrato de índice ainda se aplica, mas o carregador, os parâmetros estáticos e a validação mudam; veja a nota sobre CMS em extensions.md.
• Páginas de marketing que por acaso são Markdown. Reutilize o renderizador do host; este módulo é a navegação, pesquisa e modelo de localidade em torno de muitos artigos.

Arquitetura

content/help/<[locale]/><category>/<slug>.md
        │  gray-matter + normalização
        ▼
getHelpIndex(locale)  ── React cache(): uma análise por requisição ──┐
  categorias · artigos (ordenados) · byKey · tags · byTag · ignorados│
        │                                                        │
        ├─► páginas: landing / categoria / tag / artigo ── metadados, JSON-LD, canonical/hreflang
        ├─► HelpShell ── toSummary → árvore de navegação (barra lateral + gaveta)
        │             ── toSearchDoc → HelpSearch (cliente, pesquisa de prefixo tokenizada)
        ├─► helpSitemapEntries()
        └─► validação:help (CI) ── relacionados não resolvidos, empates de ordem, datas ruins, slugs ruins, deriva de tags

Tudo lê do índice. Nada mais toca no sistema de arquivos.

Fatos críticos

1. O sistema de arquivos é o esquema. Pasta = categoria, nome do arquivo = slug, e frontmatter são apenas metadados. slug/category no frontmatter são validados em relação ao caminho, nunca usados.
2. Apenas resumos cruzam para o cliente. toSummary/toSearchDoc removem o corpo; passar HelpArticle para um componente cliente envia todo o corpus em cada página.
3. Uma página não traduzida é uma duplicata. Ela renderiza a partir da localidade padrão, mantém seu lugar na navegação, mostra um aviso, canonicaliza para a URL da localidade padrão e está ausente de hreflang e do sitemap.
4. O tempo de execução perdoa; o CI não. Referências ruins são descartadas, ordens faltantes são classificadas por último — e validação:help falha na construção para o autor.
5. A pesquisa é do lado do cliente por design. ~1 KB por artigo, já na página para navegação, resultados na primeira tecla. Pesquisa no corpo é uma extensão.

Regras rígidas

Nunca defina uma altura máxima em uma lista colapsável. Um par max-h-* + overflow-hidden corta o que não couber e não reporta nada. Use hidden ou um primitivo colapsável real, para que uma lista renderize cada link ou nenhum.

Nunca ordene apenas por order. Empates caem para a ordem readdir, que difere entre sistemas de arquivos. Desempate por título, depois slug.

Nunca resolva related sem validá-lo. Uma referência removida é invisível na página; o validador é o único lugar onde um autor descobre que um slug foi renomeado.

Nunca pesquise uma consulta sem cortar espaços, e nunca pesquise apenas no título. Corte, tokenize, substitua diacríticos, inclua tags e cabeçalhos, classifique por campo.

Nunca codifique strings de chrome em um host com um sistema de i18n. Cada string passa por HelpStrings, para que o cabeçalho, rodapé e avisos troquem de localidade juntos.

Nunca chaveie uma tag pela sua grafia. Maiúsculas, hífens e plurais variam entre autores. Agrupe por tagSlug para que cada variante caia em uma página, e deixe o validador reportar a variação.

Início rápido

0. Preencha o contrato de interface e defina os IDs das categorias — adaptation.md.
1. Escolha o layout de conteúdo e escreva a configuração — content-model.md.
2. Copie o carregador e o analisador de frontmatter; execute o validador no conteúdo real imediatamente — content-loader.md.
3. Conecte strings e caminhos ao i18n do host — i18n.md.
4. Adicione as três páginas, ajudantes de SEO e entradas de sitemap — routes.md — em seguida, a página de tag e chips vinculados — tags.md.
5. Construa a casca, árvore de navegação e gaveta — ui.md — em seguida, o breadcrumb, cartões, listas e renderizador nos primitivos do host — ui-content.md.
6. Adicione a pesquisa e seu hook; conecte o hook de resultados zero à análise — search.md.
7. Execute os testes fornecidos e verifique o contrato de comportamento: categoria mais longa totalmente acessível, consulta com espaço à direita, consulta acentuada, canonical de página não traduzida.

Diretório de referência

Cenário	Palavras-chave de gatilho	Referência
Encaixar isso em um aplicativo existente	adaptar, interface, renomear categorias, sonda do host, integrar, dependências	adaptation.md
Frontmatter, pastas, slugs, validação	frontmatter, slug, categoria, ordem, relacionado, updatedAt, destaque, validar, CI	content-model.md
Ler arquivos no índice	carregador, gray-matter, cache, fallback, cabeçalhos, ordenação, índice, fs	content-loader.md
Caixa de pesquisa e classificação	pesquisa, combobox, classificação, tokenizar, diacríticos, prefixo, teclado, sem resultados	search.md
Tags, páginas de tag, chips, nuvem de tags	tag, tags, página de tag, chip, slug de tag, grafia, plural, navegar por tag	tags.md
Localidades, strings, datas, canônicos	i18n, localidade, tradução, fallback, hreflang, strings, plural, Intl	i18n.md
Páginas, metadados, JSON-LD, sitemap	rota, page.tsx, generateStaticParams, dynamicParams, notFound, canonical, TechArticle, sitemap	routes.md
Casca, cabeçalho, barra lateral, gaveta	layout, barra lateral, menu móvel, gaveta, colapsável, sticky, HelpShell	ui.md
Breadcrumb, cartões, listas, renderizador, hooks de estilo	breadcrumb, cartão de categoria, lista de artigos, react-markdown, data-help, estilização	ui-content.md
Além do módulo fornecido	texto completo, Pagefind, TOC, feedback, datas git, MDX, CMS, redirecionamentos	extensions.md
Por que os templates diferem da implementação anterior	proveniência, auditoria, ledger, mantido deliberadamente, corrigindo a implementação anterior	provenance.md