timerise-ai/help-center-markdown

Hilfezentrum – Markdown-Artikel, Suche, i18n

Ein Hilfezentrum ist eine kleine statische Website mit einer harten Anforderung: Jeder Artikel muss erreichbar sein – aus der Seitenleiste, aus der Suche, aus einer übersetzten Locale, die ihn noch nicht hat. Geschrieben von dem Ingenieur, der dieses Modul ausgeliefert hat; die frühere Implementierung war ein Hilfezentrum für eine Marketing-Website. Das unten stehende Modul erfüllt diese Anforderung als verifizierte Eigenschaften: Die Seitenleiste zeigt jeden Artikel jeder Kategorie, die Suche bewertet eine Abfrage unabhängig von der Eingabe, zugehörige Links werden aufgelöst oder der Validator schlägt fehl. Die Lade-, Such- und Tag-Testsuiten decken jeweils einen Bereich ab; der Nachweis befindet sich in references/provenance.md.

Wann verwenden

Beim Aufbau oder der Erweiterung eines Hilfezentrums, Dokumentsabschnitts oder einer Wissensdatenbank, deren Artikel als Markdown-Dateien im Repository vorliegen, auf Next.js App Router, mit oder ohne mehrere Locales.

Wann NICHT verwenden

• Ein Blog. Datierte, mit Autoren versehene Beiträge mit Covern und lokalisierten Slugs sind ein anderes Inhaltsmodell; behalten Sie das Blog-Modul des Hosts bei.
• Aus Code generierte Dokumentation (OpenAPI, TypeDoc) – verwenden Sie deren Generatoren und verlinken Sie auf die Ausgabe.
• Ein CMS-gestütztes Hilfesystem mit Redakteuren, die zur Laufzeit veröffentlichen – der Indexvertrag gilt weiterhin, aber der Lader, die statischen Parameter und die Validierung ändern sich; siehe die CMS-Anmerkung in extensions.md.
• Marketingseiten, die zufällig Markdown sind. Verwenden Sie den Renderer des Hosts wieder; dieses Modul ist die Navigation, Suche und das Locale-Modell für viele Artikel.

Architektur

content/help/<[locale]/><category>/<slug>.md
        │  gray-matter + Normalisierung
        ▼
getHelpIndex(locale)  ── React cache(): ein Parse pro Anfrage ──┐
  categories · articles (sortiert) · byKey · tags · byTag · skipped│
        │                                                        │
        ├─► Seiten: landing / category / tag / article ── Metadaten, JSON-LD, canonical/hreflang
        ├─► HelpShell ── toSummary → Navigationsbaum (Seitenleiste + Drawer)
        │             ── toSearchDoc → HelpSearch (Client, tokenisierte Präfixsuche)
        ├─► helpSitemapEntries()
        └─► validate:help (CI) ── unaufgelöste related, Ordnungsgleichheiten, fehlerhafte Daten, fehlerhafte Slugs, Tag-Abweichung

Alles liest aus dem Index. Nichts anderes greift auf das Dateisystem zu.

Kritische Fakten

1. Das Dateisystem ist das Schema. Ordner = Kategorie, Dateiname = Slug, und Frontmatter ist nur Metadaten. slug/category im Frontmatter werden gegen den Pfad validiert, nie verwendet.
2. Nur Zusammenfassungen gelangen zum Client. toSummary/toSearchDoc entfernen den Hauptteil; die Übergabe von HelpArticle an eine Client-Komponente würde das gesamte Korpus in jede Seite versenden.
3. Eine unübersetzte Seite ist ein Duplikat. Sie wird aus der Standard-Locale gerendert, behält ihren Platz in der Navigation, zeigt einen Hinweis, kanonisiert auf die URL der Standard-Locale und fehlt in hreflang und der Sitemap.
4. Die Laufzeit vergibt; CI nicht. Fehlerhafte Referenzen werden verworfen, fehlende Reihenfolgen werden zuletzt sortiert – und validate:help schlägt den Build für den Autor fehl.
5. Die Suche ist clientseitig konzipiert. ~1 KB pro Artikel, bereits in der Seite für die Navigation, Ergebnisse beim ersten Tastendruck. Die Voltextsuche ist eine Erweiterung.

Harte Regeln

Begrenzen Sie niemals die Höhe einer aufklappbaren Liste. Ein max-h-* + overflow-hidden-Paar schneidet ab, was nicht passt, und meldet nichts. Verwenden Sie hidden oder ein echtes Aufklapp-Primitiv, damit eine Liste jeden Link oder keinen rendert.

Sortieren Sie niemals nur nach order. Gleichstände fallen auf die readdir-Reihenfolge zurück, die sich zwischen Dateisystemen unterscheidet. Brechen Sie Gleichstände durch Titel, dann Slug.

Lösen Sie related niemals ohne Validierung auf. Eine gelöschte Referenz ist auf der Seite unsichtbar; der Validator ist der einzige Ort, an dem ein Autor erfährt, dass ein Slug umbenannt wurde.

Durchsuchen Sie niemals eine ungekürzte Abfrage und niemals nur den Titel. Kürzen, tokenisieren, Diakritika entfernen, Tags und Überschriften einbeziehen, nach Feld bewerten.

Hartcodieren Sie niemals Chrome-Strings in einem Host mit einem i18n-System. Jeder String durchläuft HelpStrings, damit Header, Footer und Hinweise gemeinsam die Locale wechseln.

Schlüsseln Sie ein Tag niemals nach seiner Schreibweise. Groß-/Kleinschreibung, Bindestriche und Pluralformen variieren zwischen Autoren. Gruppieren Sie nach tagSlug, damit jede Variante auf einer Seite landet, und lassen Sie den Validator die Abweichung melden.

Schnellstart

0. Füllen Sie den Nahtstellenvertrag aus und legen Sie die Kategorie-IDs fest – adaptation.md.
1. Wählen Sie das Inhaltslayout aus und schreiben Sie die Konfiguration – content-model.md.
2. Kopieren Sie den Lader und den Frontmatter-Parser; führen Sie den Validator sofort auf dem echten Inhalt aus – content-loader.md.
3. Verbinden Sie Strings und Pfade mit dem i18n-System des Hosts – i18n.md.
4. Fügen Sie die drei Seiten, SEO-Helfer und Sitemap-Einträge hinzu – routes.md – dann die Tag-Seite und verlinkte Chips – tags.md.
5. Bauen Sie die Hülle, den Navigationsbaum und den Drawer – ui.md – dann Breadcrumb, Karten, Listen und Renderer auf den Primitiven des Hosts – ui-content.md.
6. Integrieren Sie die Suche und ihren Hook; verbinden Sie den Hook für null Ergebnisse mit der Analyse – search.md.
7. Führen Sie die ausgelieferten Tests aus und überprüfen Sie dann das Verhaltensvertrag: längste Kategorie vollständig erreichbar, Abfrage mit nachstehendem Leerzeichen, Abfrage mit Akzent, Kanonische der unübersetzten Seite.

Referenzverzeichnis

Szenario	Trigger-Keywords	Referenz
Einfügen in eine bestehende App	anpassen, Nahtstelle, Kategorien umbenennen, Host-Prüfung, integrieren, Abhängigkeiten	adaptation.md
Frontmatter, Ordner, Slugs, Validierung	frontmatter, slug, category, order, related, updatedAt, featured, validate, CI	content-model.md
Dateien in den Index einlesen	loader, gray-matter, cache, fallback, headings, sort, index, fs	content-loader.md
Suchfeld und Ranking	search, combobox, ranking, tokenize, diacritics, prefix, keyboard, no results	search.md
Tags, Tag-Seiten, Chips, Tag-Cloud	tag, tags, tag page, chip, tag slug, spelling, plural, browse by tag	tags.md
Locales, Strings, Daten, Kanonische	i18n, locale, translation, fallback, hreflang, strings, plural, Intl	i18n.md
Seiten, Metadaten, JSON-LD, Sitemap	route, page.tsx, generateStaticParams, dynamicParams, notFound, canonical, TechArticle, sitemap	routes.md
Hülle, Header, Seitenleiste, Drawer	layout, sidebar, mobile menu, drawer, collapsible, sticky, HelpShell	ui.md
Breadcrumb, Karten, Listen, Renderer, Style-Hooks	breadcrumb, category card, article list, react-markdown, data-help, styling	ui-content.md
Über das ausgelieferte Modul hinaus	full-text, Pagefind, TOC, feedback, git dates, MDX, CMS, redirects	extensions.md
Warum sich die Vorlagen von der früheren Implementierung unterscheiden	provenance, audit, ledger, kept deliberately, fixing the earlier implementation	provenance.md