Erstellen einer lokalen Vorschau

Fedora-Dokumentationsteam Last review: 2023-03-19
Eine lokale Vorschau ist ein wertvolles Werkzeug, um Ihre Änderungen in Ihrer lokalen Entwicklungsumgebung zu testen. Führen Sie das im Fedora-Content-Repository verfügbare Docsbuilder-Skript aus. Sie können die vollständig gerenderte Website auf Ihrem Rechner erstellen und ausführen, um Ihre Änderungen vor dem Einreichen eines Pull Requests an die Fedora-Content-Repositories zu überprüfen.

Wann Sie eine lokale Vorschau brauchen

Bei der Arbeit mit einer lokalen Entwicklungsumgebung bietet eine lokale Vorschau einen vielseitigen Arbeitsablauf, um zu testen, wie die Änderungen lokal in Ihrem Browser dargestellt werden und funktionieren. Wenn Sie Änderungen vornehmen, wie beispielsweise (aber nicht ausschließlich):

  • Links ändern oder defekte Links reparieren

  • Dokument-zu-Dokument-Querverweise (xref) ändern

  • Mehrere Seiten zu einer Seite zusammenfassen

  • Abbildungen aktualisieren oder fehlerhafte Abbildungen reparieren

  • Metadaten oder Alternativtext zu Abbildungen hinzufügen

  • Die Abschnittsebenen zur Verbesserung der Lesbarkeit und des Leseflusses neu anordnen (Beispiel: h2 zu h3, h3 zu h4)

  • Inaktive Navigationsleiste reparieren

  • Navigationsleiste neu organisieren

  • Veraltete Seiten überarbeiten oder neu schreiben

  • AsciiDoc-Attribute hinzufügen

  • Änderungen wiederholen und mit dem Vale-Linter testen

Sie benötigen Build-Skripte, um die Änderungen vorhersehbar darzustellen und zu testen, bevor Sie einen Pull Request erstellen.

Was die Skripte bewirken

Ein vereinheitlichtes Dokumentations-Bauskript, docsbuilder.sh, erstellt eine lokale Version der Webseite. Dies ist ein Teil der vollständigen Webseite, der in Ihrem lokalen Repository gespeichert wird. Anschließend startet das Skript einen Webserver und stellt die Webseite unter http://localhost:8080/ bereit. Wenn Sie diesen Link in einem beliebigen Webbrowser öffnen, wird Ihnen die Vorschau angezeigt, die so lange verfügbar ist, bis Sie den Prozess beenden (kbd:[Strg+C] im Terminal).

Lesen Sie die Datei README.md auf der Startseite des Projekts, um das empfohlene Skript auszuführen.

Testen der Änderungen

Wechseln Sie in das Verzeichnis, in dem sich das geklonte Repository befindet, und führen Sie die Bauskripte im Terminal aus, um die Webseite zu erstellen, zu überwachen und eine Vorschau anzuzeigen.

$ ./docsbuilder.sh

Pagure oder andere Inhaltsrepositorys zeigen ein anderes Bauskript an.

$ ./builder.sh

Um die Skripte verwenden zu können, benötigen Sie Podman unter Fedora oder Docker CE unter macOS.

Vorschau auf mehrere Repositories

Wenn sich Ihre Arbeit über Inhalte in mehreren Repositories erstreckt, z.B. weil Sie einen Link zu einem anderen Repository verwenden, können Sie die Vorschau erweitern, indem Sie weitere Repositories zu site.yml hinzufügen, wie folgt:

content:
  sources:
  - url: .
    branches: HEAD
  - url: https://pagure.io/fedora-docs/another-repository.git
    branches: main

Die korrekten Einträge finden Sie unter docs-fp-o site.yml.

Verwendung der regulären Antora-Skripte

Wenn Sie den regulären Antora-Build- und Vorschau-Arbeitsablauf verwenden möchten, folgen Sie den Anweisungen auf der Antora-Dokumentationsseite.

Sobald Sie „Antora CLI“ und „Antora Site Generator“ haben, können Sie die Seiten ohne die Container-Skripte erstellen und in der Vorschau anzeigen.

Um die Seiten im Projektverzeichnis zu erstellen, führen Sie Folgendes aus:

antora generate site.yml

Dadurch wird ein neues Verzeichnis „public“ erstellt, das alle notwendigen Dateien enthält. Wechseln Sie in dieses Verzeichnis und führen Sie einen Serverbefehl aus. Möglicherweise haben Sie bereits einen einfachen Python-Server; in diesem Fall führen Sie Folgendes aus:

python3 -m http.server

oder wenn Sie nur Python 2 auf Ihrem Rechner haben:

python -m SimpleHTTPServer

Dadurch wird eine lokale Vorschau auf Port 8000 geöffnet.

Falls Sie über Cargo (den Rust-Paketmanager) verfügen, können Sie auch miniserve oder einen anderen einfachen Server Ihrer Wahl installieren und verwenden.

Want to help? Learn how to contribute to Fedora Docs ›