timerise-ai/help-center-markdown

Centro de Ayuda — artículos en markdown, búsqueda, i18n

Un centro de ayuda es un sitio estático pequeño con un requisito estricto: cada artículo debe ser accesible — desde la barra lateral, desde la búsqueda, desde un locale traducido que aún no lo tenga. Escrito por el ingeniero que ha implementado este módulo; la implementación anterior era un centro de ayuda para un sitio de marketing. El módulo a continuación mantiene ese requisito como propiedades verificadas: la barra lateral muestra cada artículo de cada categoría, la búsqueda clasifica una consulta sin importar cómo se escriba, los enlaces relacionados se resuelven o el validador falla la compilación. El cargador, la búsqueda y los conjuntos de etiquetas cubren cada uno; el registro está en references/provenance.md.

Cuándo usar

Construir o extender un centro de ayuda, sección de documentación o base de conocimiento cuyos artículos son archivos markdown en el repositorio, en Next.js App Router, con o sin múltiples locales.

Cuándo NO usar

• Un blog. Publicaciones con fecha, autor, portada y slugs localizados son un modelo de contenido diferente; mantén el módulo de blog del host.
• Documentación generada desde código (OpenAPI, TypeDoc) — usa sus generadores y enlaza a la salida.
• Un sitio de ayuda respaldado por CMS con editores publicando en tiempo de ejecución — el contrato del índice aún aplica, pero el cargador, los parámetros estáticos y la validación cambian; consulta la nota de CMS en extensions.md.
• Páginas de marketing que resultan ser markdown. Reutiliza el renderizador del host; este módulo es la navegación, búsqueda y modelo de idioma alrededor de muchos artículos.

Arquitectura

content/help/<[locale]/><category>/<slug>.md
        │  gray-matter + normalización
        ▼
getHelpIndex(locale)  ── React cache(): un análisis por solicitud ──┐
  categorías · artículos (ordenados) · byKey · etiquetas · byTag · omitidos│
        │                                                        │
        ├─► páginas: inicio / categoría / etiqueta / artículo ── metadatos, JSON-LD, canonical/hreflang
        ├─► HelpShell ── toSummary → árbol de navegación (barra lateral + cajón)
        │             ── toSearchDoc → HelpSearch (cliente, búsqueda de prefijo tokenizada)
        ├─► helpSitemapEntries()
        └─► validate:help (CI) ── relacionados no resueltos, empates de orden, fechas incorrectas, slugs incorrectos, deriva de etiquetas

Todo se lee desde el índice. Nada más toca el sistema de archivos.

Hechos críticos

1. El sistema de archivos es el esquema. Carpeta = categoría, nombre de archivo = slug, y el frontmatter es solo metadatos. slug/category en frontmatter se validan contra la ruta, nunca se usan.
2. Solo los resúmenes cruzan al cliente. toSummary/toSearchDoc eliminan el cuerpo; pasar HelpArticle a un componente cliente envía todo el corpus en cada página.
3. Una página no traducida es un duplicado. Se renderiza desde el locale predeterminado, mantiene su lugar en la navegación, muestra un aviso, se canoniciza a la URL del locale predeterminado y está ausente de hreflang y del sitemap.
4. El tiempo de ejecución perdona; CI no. Las referencias incorrectas se eliminan, los órdenes faltantes se ordenan al final — y validate:help falla la compilación para el autor.
5. La búsqueda es del lado del cliente por diseño. ~1 KB por artículo, ya en la página para navegación, resultados al primer golpe de tecla. La búsqueda en el cuerpo es una extensión.

Reglas estrictas

Nunca limites la altura de una lista colapsable. Un max-h-* + overflow-hidden recorta lo que no cabe y no reporta nada. Usa hidden o un primitivo colapsable real, para que una lista renderice cada enlace o ninguno.

Nunca ordenes solo por order. Los empates caen al orden de readdir, que difiere entre sistemas de archivos. Rompe empates por título, luego por slug.

Nunca resuelvas related sin validarlo. Una referencia eliminada es invisible en la página; el validador es el único lugar donde un autor se entera de que un slug fue renombrado.

Nunca busques una consulta sin recortar, y nunca busques solo el título. Recorta, tokeniza, pliega diacríticos, incluye etiquetas y encabezados, clasifica por campo.

Nunca codifiques cadenas de interfaz en un host con un sistema i18n. Cada cadena pasa por HelpStrings, para que el encabezado, pie de página y avisos cambien de locale juntos.

Nunca asocies una etiqueta por su ortografía. Mayúsculas, guiones y plurales varían entre autores. Agrupa por tagSlug para que cada variante aterrice en una página, y deja que el validador reporte la deriva.

Inicio rápido

0. Completa el contrato de integración y define los ids de las categorías — adaptation.md.
1. Elige el diseño del contenido y escribe la configuración — content-model.md.
2. Copia el cargador y el analizador de frontmatter; ejecuta el validador sobre el contenido real inmediatamente — content-loader.md.
3. Conecta las cadenas y rutas al i18n del host — i18n.md.
4. Añade las tres páginas, ayudas SEO y entradas de sitemap — routes.md — luego la página de etiquetas y chips vinculados — tags.md.
5. Construye el shell, el árbol de navegación y el cajón — ui.md — luego el breadcrumb, tarjetas, listas y renderizador sobre los primitivos del host — ui-content.md.
6. Incorpora la búsqueda y su hook; conecta el hook de cero resultados a analíticas — search.md.
7. Ejecuta las pruebas incluidas, luego verifica el contrato de comportamiento: categoría más larga completamente accesible, consulta con espacio final, consulta acentuada, canonical de página no traducida.

Directorio de referencia

Escenario	Palabras clave de activación	Referencia
Integrar esto en una aplicación existente	adapt, costura, renombrar categorías, sondeo del host, integrar, dependencias	adaptation.md
Frontmatter, carpetas, slugs, validación	frontmatter, slug, categoría, orden, relacionados, updatedAt, destacado, validar, CI	content-model.md
Leer archivos en el índice	cargador, gray-matter, caché, respaldo, encabezados, ordenar, índice, fs	content-loader.md
Cuadro de búsqueda y clasificación	búsqueda, combobox, clasificación, tokenizar, diacríticos, prefijo, teclado, sin resultados	search.md
Etiquetas, páginas de etiquetas, chips, nube de etiquetas	etiqueta, etiquetas, página de etiqueta, chip, slug de etiqueta, ortografía, plural, navegar por etiqueta	tags.md
Locales, cadenas, fechas, canonicales	i18n, locale, traducción, respaldo, hreflang, cadenas, plural, Intl	i18n.md
Páginas, metadatos, JSON-LD, sitemap	ruta, page.tsx, generateStaticParams, dynamicParams, notFound, canonical, TechArticle, sitemap	routes.md
Shell, encabezado, barra lateral, cajón	layout, barra lateral, menú móvil, cajón, colapsable, sticky, HelpShell	ui.md
Breadcrumb, tarjetas, listas, renderizador, hooks de estilo	breadcrumb, tarjeta de categoría, lista de artículos, react-markdown, data-help, estilizado	ui-content.md
Más allá del módulo incluido	texto completo, Pagefind, TOC, retroalimentación, fechas de git, MDX, CMS, redirecciones	extensions.md
Por qué las plantillas difieren de la implementación anterior	procedencia, auditoría, registro, mantenido deliberadamente, arreglando la implementación anterior	provenance.md