MDX-Dokumentationsseiten schreiben, die den Regeln der Website folgen und fehlerfrei bauen

## Vor dem Schreiben verstehen, wie die Dokumentationswebsite aufgebaut ist Behandeln Sie das Repository als schemagesteuerte Dokumentationsanwendung und nicht als lose Sammlung von Markdown-Dateien. Bestimmen Sie Webseitengenerator, Dokumentationsthema, Komponentenrahmen, Paketverwaltung, Laufzeitversion und Bereitstellungsziel. Installieren Sie Abhängigkeiten mit dem festgeschriebenen, reproduzierbaren Befehl des Repositorys. Stimmen Sie die Versionen von Laufzeit und Paketverwaltung mit den Repository-Metadaten ab. Bestätigen Sie den primären Beitrags-Branch, statt einen üblichen Namen anzunehmen. Unterscheiden Sie benutzerorientierte Seiten, wiederverwendbare Teiltexte, Änderungsprotokolle, Glossardaten, Produktmetadaten und andere strukturierte Sammlungen. Halten Sie benutzerdefinierte Komponenten, Inhaltsschemata, Markdown-Erweiterungen, Codehervorhebungs-Erweiterungen, Symbole, Ressourcen, Stile und dynamische Routen in den jeweils vorgesehenen Schichten. Behandeln Sie statische öffentlich bereitgestellte Dateien anders als Bilder, die der Webseitengenerator verarbeitet. Verwenden Sie das zentrale Komponentenexportmodul als öffentliche Importschnittstelle für MDX. Behandeln Sie Sammlungsschemata als maßgebliche Quelle für akzeptierte Felder und Werttypen. Behandeln Sie erzeugte Skill- oder Referenzverzeichnisse als Build-Produkte. Bearbeiten Sie keine erzeugten Verzeichnisse und nehmen Sie keine ignorierten erzeugten Inhalte in einen Commit auf. Lesen Sie verschachtelte Anweisungen, bevor Sie einen spezialisierten Prüfbot oder Bereitstellungsprozess ändern. Verwenden Sie repositoryspezifische Stil-, Komponenten- und Verfahrensreferenzen als maßgebliche Anleitung. Lassen Sie allgemeine Markdown-Gewohnheiten nicht die MDX- und Schemaregeln der Website außer Kraft setzen. ## Seiten in die richtigen Ordner legen und Dateien richtig benennen Legen Sie Dokumentationsseiten für Benutzer unter dem Produkt- oder Themenverzeichnis ab. Legen Sie wiederverwendbare Textbausteine in der Teiltextsammlung ab. Legen Sie Änderungsprotokolleinträge im passenden Produkt- oder Themenunterverzeichnis ab. Legen Sie Glossarbegriffe und andere strukturierte Metadaten in den von ihrem Schema verwalteten Sammlungen ab. Verlangen Sie in jedem navigierbaren Inhaltsordner eine Indexseite, wenn die Website eine erwartet. Verwenden Sie kleingeschriebene Dateinamen, deren Wörter durch Bindestriche getrennt sind. Beschränken Sie Inhaltsverzeichnisse auf die ausdrücklich zugelassenen Text- und Datendateiendungen. Typischerweise zulässig sind MDX, JSON, YAML und reiner Text. Lassen Sie die Dateiendungsprüfung die Zulassungsliste durchsetzen, statt nicht unterstützte Dateien zu verbergen. Legen Sie keine Bilder oder beliebigen Binärdateien in schemagescannten Inhaltsverzeichnissen ab. Legen Sie verarbeitbare Bilder zur Optimierung im dafür vorgesehenen Ressourcenbaum ab. Legen Sie wirklich statische Dateien nur dann im öffentlichen Verzeichnisbaum ab, wenn sie unverändert ausgeliefert werden müssen. Stimmen Sie Verzeichnisnamen mit vorhandenen Produktmetadaten ab. Erstellen Sie für einen unbekannten Produktschlüssel kein Änderungsprotokoll- oder Sammlungsunterverzeichnis. Bewahren Sie etablierte Sammlungsgrenzen, statt einen parallelen Ablageort für Inhalte zu erfinden. Aktualisieren Sie beim Verschieben einer Seite eingehende Verweise, Navigationsmetadaten, Weiterleitungen und zugehörige Teiltextverweise. ## Die geforderten Seitenangaben (Frontmatter) ausfüllen Geben Sie jeder Dokumentationsseite einen Frontmatter-Block, der ihr Sammlungsschema erfüllt. Geben Sie einen knappen Seitentitel an. Geben Sie stets eine Suchbeschreibung an, wenn der gewählte Inhaltstyp sie verlangt. Wählen Sie den Seitentyp aus der im Repository zugelassenen Aufzählung. Gängige Typen sind `concept`, `configuration`, `example`, `FAQ`, `getting started`, `how-to`, `integration`, `implementation`, `overview`, `reference`, `release notes`, `solution`, `troubleshooting` und `tutorial`. Verwenden Sie spezialisierte Typen wie `design guide`, `learning unit`, `navigation`, `reference architecture` und `video`, wenn das Schema sie bereitstellt. Verwenden Sie die Seitenleistenreihenfolge nur, wenn eine ausdrückliche Sortierung erforderlich ist. Verwenden Sie eine Seitenleistenbeschriftung nur, wenn der Navigationstext vom Seitentitel abweichen soll. Verweisen Sie über vorhandene Metadatenschlüssel auf Produkte oder Themen. Verwenden Sie für Anleitungsinhalte die dokumentierte Schwierigkeitsaufzählung. Erfassen Sie Prüfdaten im vorgeschriebenen Jahr-Monat-Tag-Format. Erfinden Sie keine Schemafelder oder Aufzählungswerte. Halten Sie YAML-Einrückung und Listenstruktur gültig. Erzeugen Sie nach Änderungen an Sammlungsdefinitionen oder Schemata die Inhaltssammlungstypen neu. Validieren Sie Datendateien anhand ihres Schemas, statt sich auf Sichtprüfung zu verlassen. Halten Sie Seitenmetadaten synchron, wenn sich Zweck, Produkt, Titel oder Prüfstatus der Seite ändern. ## MDX-Seiten ohne Syntaxfehler schreiben, damit sie sich bauen lassen Befolgen Sie den maßgeblichen Schreib- und Formatierungsleitfaden des Repositorys. Behandeln Sie MDX als Markdown mit einer eingebetteten Komponentensprache und strengerer Syntaxanalyse. Maskieren Sie geschweifte und spitze Klammern oder formatieren Sie sie als Code, wenn sie als Fließtext gemeint sind. Beachten Sie, dass MDX diese Zeichen auch im Fließtext als Ausdrücke oder Komponenten interpretiert. Importieren Sie jede Komponente, die auf der Seite verwendet wird. Platzieren Sie Importe unmittelbar nach dem Frontmatter und vor dem Seiteninhalt. Verwenden Sie nur unterstützte Sprachkennungen für die Syntaxhervorhebung. Schreiben Sie allgemeine Terminalausgaben mit der Kennung des Repositorys für reinen Text. Verwenden Sie in Codeblöcken kleingeschriebene Sprachkennungen. Verwenden Sie für interne Websiteverweise absolute Pfade ab dem Wurzelverzeichnis. Verwenden Sie für interne Ziele keine vollständigen Produktions-URLs. Verwenden Sie keine nicht unterstützten relativen Seitenverweise. Halten Sie Überschriftenebenen fortlaufend und überspringen Sie keine Ebene. Lassen Sie Shell-Eingabeaufforderungszeichen aus kopierbaren Befehlen weg. Schreiben Sie knappe Schritte, deren Handlung, Ort und erwartetes Ergebnis eindeutig sind. Bewahren Sie wiederverwendbare Erklärungen in Teiltexten auf, wenn mehrere Seiten denselben gepflegten Text benötigen. Prüfen Sie Codebeispiele anhand der dokumentierten API und des aktuellen Produktverhaltens. ## Komponenten und Bilder der Website nutzen und Weiterleitungen nur bei Bedarf ändern Importieren Sie MDX-Komponenten ausschließlich über das zentrale Komponenten-Sammelexportmodul des Repositorys. Lesen Sie in der Komponentendokumentation die erforderlichen Eigenschaften und Nutzungsbeschränkungen nach. Kopieren Sie keine internen Komponentenbestandteile in Inhalte, wenn eine unterstützte öffentliche Komponente vorhanden ist. Legen Sie neuen Komponentencode im vorgesehenen Komponentenverzeichnis ab. Verwenden Sie das vorgeschriebene Präfix für benutzerdefinierte Elemente und die Namenskonvention aus kleingeschriebenen, bindestrichgetrennten Wörtern. Bewahren Sie jede Komponente in einem nach ihr benannten Verzeichnis auf. Verwenden Sie PascalCase-Klassennamen mit dem erforderlichen Suffix. Benennen Sie ausgenommene Bestandselemente nicht nur um, um eine neuere Präfixregel anzuwenden. Bewahren Sie Quellbilder im optimierten Ressourcenverzeichnis für ihr Produkt oder Thema auf. Prüfen Sie Bildpfade mit einem vollständigen lokalen Build. Ändern Sie Weiterleitungen nur, wenn ein Seitenumzug oder eine URL-Migration dies erfordert. Beenden Sie Weiterleitungsquellpfade mit dem erforderlichen Schrägstrich oder einem zulässigen Datei- oder Platzhaltersuffix. Nehmen Sie keine Fragmente in Weiterleitungsquell-URLs auf. Erkennen Sie Weiterleitungsschleifen vor der Prüfung. Führen Sie bei jeder Änderung der Weiterleitungsdatei den dafür vorgesehenen Weiterleitungsvalidator aus. Beschränken Sie Änderungen an Komponenten, Bildern, Verweisen und Weiterleitungen auf den vorgesehenen Seitenumfang. ## Lokal und in der CI die nötigen Prüfungen bestehen, bevor eine Seite als fertig gilt Führen Sie nach jeder Inhaltsänderung Schema- und Typprüfungen aus. Verwenden Sie einen vollständigen lokalen Build, um MDX-Analyse, Bildpfade und interne Verweise zu validieren. Aktivieren Sie die interne Verweisprüfung während des vollständigen lokalen Validierungs-Builds. Führen Sie in einer eingeschränkten CI keinen vollständigen Build aus, dessen Zeitüberschreitung bekannt ist. Führen Sie in der CI Typprüfung, statische Codeprüfung und Formatierungsprüfung als verkleinerte sichere Menge aus. Führen Sie bei Codeänderungen außerdem die vollständigen Testsuiten des Repositorys aus. Formatieren Sie jede bearbeitete Datei vor dem Commit. Führen Sie nach automatischen Korrekturen die Formatierungsprüfung des Repositorys aus. Führen Sie die Weiterleitungsvalidierung nur aus, wenn sich die Weiterleitungskonfiguration geändert hat. Führen Sie nach Schema- oder Sammlungsänderungen die Sammlungstypsynchronisierung aus. Stimmen Sie die vollständige lokale Validierungsfolge nach Möglichkeit mit der CI-Pipeline ab. Rechnen Sie damit, dass die CI Dateiendungen, Typen, statische Codeprüfung, Formatierung, Build und Verweise, Weiterleitungen sowie Tests prüft. Behandeln Sie Warnungen des Stilprüfers als Prüfbelege, auch wenn sie keine harten Fehler sind. Melden Sie eine Seite nicht als fertig, solange eine direkt relevante Validierungsschranke fehlt. Unterscheiden Sie eine Einschränkung der CI-Umgebung von einem tatsächlichen Inhaltsfehler. Führen Sie direkt betroffene Prüfungen nach jeder Korrekturbearbeitung erneut aus. ## Jedem Verzeichniseintrag eine vom Werkzeug erzeugte ID geben und sie beibehalten Geben Sie jeder Datendatei eines Verzeichniseintrags an der vorgeschriebenen Position in der ersten Zeile eine eindeutige, stabile Kennung. Verwenden Sie die exakte Kennungslänge und den verwechslungsarmen Zeichensatz des Repositorys. Prüfen Sie bei einem Sechs-Zeichen-Schema, dass jeder erzeugte Wert genau sechs Zeichen umfasst. Schließen Sie optisch mehrdeutige Zeichen aus, wenn das Schema dies verlangt. Erzeugen Sie Kennungen zufällig, statt sie aus Namen abzuleiten. Erstellen, erraten oder kopieren Sie eine Kennung nicht von Hand. Prüfen Sie mit dem Kennungswerkzeug des Repositorys die vollständige Sammlung. Verwenden Sie dessen Korrekturmodus für fehlende, fehlerhaft formatierte oder doppelte Kennungen. Bewahren Sie eine vorhandene gültige Kennung, wenn sich Anzeigename oder Dateiname ändern. Ändern Sie eine vorhandene Kennung nur, um einen bestätigten Validierungsfehler zu beheben. Verwenden Sie durchgängig die eine vorgeschriebene YAML-Dateiendung. Behandeln Sie die Kennungserzeugung als automatisierten Vorgang und nicht als redaktionelle Entscheidung. Prüfen Sie die Eindeutigkeit in der gesamten Verzeichnissammlung. Belassen Sie Kennungserzeugung und Schemavalidierung in der CI. Prüfen Sie die vom Werkzeug erzeugte Differenz, bevor Sie Änderungen als Commit erfassen. Passen Sie eine erzeugte Kennung nach erfolgreichem Abschluss des Werkzeugs nicht manuell an. ## Beim Einreichen von Änderungen den Aufgabenanleitungen und Commit-Regeln folgen Verwenden Sie den Beitragsrouter des Repositorys, bevor Sie schreiben, bearbeiten, Beispiele prüfen, Änderungsprotokolle ergänzen oder einen Pull-Request vorbereiten. Befolgen Sie die aufgabenspezifische Referenz, die dieser Router auswählt. Lesen Sie die lokalen Anweisungen eines spezialisierten Bots, bevor Sie dessen Code, Arbeitsablaufrouting, Zustand oder Bereitstellung ändern. Halten Sie werkzeugspezifische symbolische Verknüpfungen auf die als Commit erfasste gemeinsame Agentenkonfiguration gerichtet. Laden Sie einen Repository-Skill nur, wenn dessen Beschreibung zur Aufgabe passt. Verwenden Sie den maßgeblichen Stilleitfaden für Text- und Formatierungsentscheidungen. Verwenden Sie den Komponentenkatalog für Eigenschaften, Beispiele und verbindliche Muster. Verwenden Sie den Verfahrensleitfaden für schrittweise Anweisungen. Führen Sie Tests in jedem von einer Codeänderung betroffenen Laufzeitarbeitsbereich aus. Halten Sie Tests für Arbeitsprozesse, Serverlaufzeit und Webseitengenerator voneinander getrennt. Verfassen Sie Commits in der vom Repository akzeptierten Form mit Produkt- oder Typpräfix. Richten Sie Commit-Beschreibungen gezielt auf die benutzersichtbare oder technische Korrektur aus. Nehmen Sie keine sachfremden Formatierungen, erzeugten Inhalte oder Produktänderungen auf. Genehmigen Sie nur, wenn Inhalte, Schemata, Importe, Ressourcen, Verweise, Weiterleitungen, Tests und Beitragskonventionen übereinstimmen.