Aufbau der NextPDF-Dokumentation

Auf einen Blick

Das NextPDF-Handbuch folgt beim Wachstum einem festen Vertrag. Jede Seite behandelt ein Thema, hat einen Diataxis-Modus und eine Seitenart. Jede Seitenart hat einen fest vorgeschriebenen Satz von Überschriften der Ebene 2. Einige wenige Manifeste und Gates halten die Struktur sauber, während das Handbuch wächst.

Diese Seite skizziert die Form dieses Systems, damit Ihr Beitrag am richtigen Ort ankommt. Der vollständige normative Vertrag, einschließlich der genauen Überschriftenlisten, der Zitierregeln und der schrittweisen Gate-Einbindungsprozedur, liegt im internen Governance-Dokument docs/style/expansion-standard.md. Lesen Sie zuerst diese Seite; ziehen Sie das Governance-Dokument hinzu, wenn Sie schreiben.

Eine Seitenart wählen

Wenden Sie die folgenden Regeln der Reihe nach an, um zu entscheiden, ob Sie eine Seite hinzufügen oder eine bestehende erweitern:

1. Wenn der Inhalt ein eigenständiges Thema ist, das Leserinnen und Leser auf der bestehenden Seite nicht erwarten würden, legen Sie eine neue Seite an.
2. Wenn der Inhalt ein Thema vervollständigt, das die bestehende Seite bereits behandelt, erweitern Sie diese Seite.
3. Wenn der Inhalt sehr detailliert ist und eine Installations-, Schnellstart- oder Aufgabenseite aufblähen würde, verschieben Sie ihn auf eine eigene Seite und verlinken Sie darauf.
4. Andernfalls erweitern Sie die bestehende Seite.

Sobald feststeht, dass es die Seite geben soll, legen Sie ihren Diataxis-Modus fest; er bestimmt die Seitenart:

• Tutorial vermittelt einer lernenden Person etwas; verwenden Sie daher einen Aufgabenleitfaden, der als Recipe geschrieben ist.
• How-to hilft kompetenten Leserinnen und Lesern, eine Aufgabe abzuschließen; verwenden Sie daher einen Aufgabenleitfaden, einen Server-API-Leitfaden oder einen SDK-Leitfaden.
• Reference nennt exakte Fakten; verwenden Sie daher eine API-Referenz oder eine Index-Seite.
• Explanation baut Verständnis auf; verwenden Sie daher einen Entwicklerleitfaden oder einen Premium-Feature-Leitfaden.

Klare Sprache ist in jedem Modus die Grundlage, aber kein eigener Modus.

Der Seitenartenkatalog

Der Handbuchvertrag definiert diese Arten. Verwenden Sie eine bestehende Art wieder, sobald Ihre Seite eine API-Tabelle enthält; führen Sie eine neue, reine Labelart nur für eine Seite ohne API-Tabelle ein.

• Indexarten: section-index, api-index, extension-index.
• Referenzart: api-reference. Verwenden Sie sie für jede Seite mit der Standard-API-Tabelle wieder, auch für Server- und Python-SDK-Referenzen.
• Explanation-Art: developer-guide. Verwenden Sie sie für Architektur-, Lebenszyklus- und Erweiterungspunkt-Prosa wieder, auch für Server- und Python-SDK-Leitfäden.
• Neue, reine Labelarten: premium-feature-guide und task-guide, beide für Seiten ohne API-Tabelle.

Jede Seite beginnt mit ## At a glance. Jede api-reference-Seite enthält die gemeinsame API-Tabelle und die Überschrift Development notes. Vorgeschriebene Überschriften stehen genau auf Ebene 2, jeweils in einer eigenen Zeile; darunter dürfen Sie weitere Überschriften ergänzen.

Checkliste fürs Schreiben

Wenn Sie eine Seite schreiben, erfüllen Sie beide folgenden Checklisten. Der interne Standard formuliert jeden Punkt normativ und verweist auf den Standard, auf dem er beruht.

Entwicklerfreundlichkeit:

• Beziehen Sie lauffähige Beispiele aus examples/ oder tests/Cookbook und geben Sie jedem umrahmten Block einen title=-Info-String.
• Nennen Sie Voraussetzungen im Front-Matter und im Einstieg.
• Zeigen Sie die erwartete Ausgabe für jedes Beispiel, das eine erzeugt.
• Halten Sie Blöcke copy-paste-fertig: eine Sprache pro Block, vollständige Namen bei der ersten Verwendung, keine nachgestellten Prompt-Zeichen.
• Zeigen Sie standardmäßig sicheren Code: Produktionsbeispiele nutzen try/catch mit der spezifischsten NextPDF-Exception und niemals ein leeres catch.
• Schließen Sie mit weiterführenden Links ab und setzen Sie im Front-Matter related:.

Übersetzungsbereitschaft:

• Schreiben Sie einen Gedanken pro Satz, damit die maschinelle Übersetzung nicht ausufert.
• Halten Sie Überschriften und Beschriftungen kurz, weil die meisten Zielsprachen länger werden.
• Vermeiden Sie Redewendungen.
• Belassen Sie Symbolnamen, Config-Schlüssel, CLI-Flags und Exception-Namen in Code-Formatierung; Standardnamen wie PDF/A-4, PAdES und eIDAS werden niemals übersetzt.
• Setzen Sie i18n_ready und xliff_segments ehrlich und schreiben Sie in Unicode NFC.

Befolgen Sie für Tonfall, Codebeispiele, Terminologie und Zitierstil das verabschiedete Style-Override-Sheet, auf das der interne Standard verweist.

Gate-Einbindung

Eine neue Seite wird nach einer geordneten Prozedur eingebunden:

1. Legen Sie das Seitengerüst so an, dass ihr Front-Matter zum Site-Schema passt.
2. Schreiben Sie den Hauptteil entsprechend den vorgeschriebenen Überschriften der Seitenart.
3. Fügen Sie einen { path, owner, kind, headings[] }-Eintrag zu docs/manual-contract.json hinzu. Der Pfad ist relativ zu src/content/docs, verwendet Schrägstriche und enthält weder einen führenden Schrägstrich noch ...
4. Fügen Sie bei einer API-Referenz die Symbole der Seite zu docs/api-coverage-manifest.json hinzu; jedes Symbol muss auf der Seite erscheinen und im Quellcode existieren.
5. Aktualisieren Sie docs/source-manifest.json nur, wenn die Seite aus einem neuen Quell-Repository stammt.
6. Fügen Sie die Seite als expliziten Eintrag der richtigen Seitenleistengruppe in astro.config.mjs hinzu.
7. Fügen Sie für eine rein englische Seite eine Locale-Coverage-Zeile hinzu, bei der alle siebzehn Locale-Zellen auf missing gesetzt sind.
8. Führen Sie die Dokumentations-Gates, den Build und das Performance-Budget aus.

Site-eigene Seiten liegen unter src/content/docs, setzen owner auf nextpdf-docs und tragen niemals einen Aggregationsmarker. Aggregierte Seiten stammen aus einem Quell-Repository, und ihr Publish-Flag liegt im Quell-Front-Matter; bearbeiten Sie sie daher dort, nicht hier.

Siehe auch

• Integrationen: das größte ausgearbeitete Beispiel für die Handbuchform über viele Pakete hinweg.
• Das interne Governance-Dokument docs/style/expansion-standard.md enthält den vollständigen Vertrag: die genauen Überschriftenlisten für jede Seitenart, die Zitierregeln und die komplette Gate-Einbindungsprozedur.