AsciiDoc-Markup

Fedora-Dokumentationsteam <https://discussion.fedoraproject.org/tag/docs-team> v1.0, 10. Dezember 2022

Diese Seite enthält allgemeine Informationen zum Schreiben in AsciiDoc sowie zur Fedora/Antora-spezifischen Syntax, die häufig in der Fedora-Dokumentation vorkommt.

AsciiDoc-Grundlagen

AsciiDoc ist eine leichtgewichtige Auszeichnungssprache zum Verfassen von Notizen, Artikeln, Dokumentationen, Büchern, Webseiten, Präsentationen und Handbuchseiten im Klartext.

— asciidoctor.org
Schnellreferenz zur AsciiDoc-Syntax

Praktische Übersicht zur AsciiDoc-Auszeichnung. Nutzen Sie diese für schnelles Nachschlagen und Informationen zur Formatierung von Listen, Medieninhalten (Bilder und Videos), Inhaltsverzeichnissen und mehr.

Bewährte Vorgehensweisen für AsciiDoc

Bewährte Vorgehensweisen beim Schreiben in AsciiDoc. Am wichtigsten ist, dass jeder Satz in einer eigenen Zeile stehen sollte.

Fedora-Dokumentationsschnipsel

Beim Schreiben der Fedora-Dokumentation tauchen einige Dinge häufig auf. Diese sind möglicherweise nicht in der allgemeinen AsciiDoc-Dokumentation, wie beispielsweise auf asciidoctor.org, dokumentiert. + Dieser Abschnitt enthält hilfreiche Referenzen für Fedora-Dokumentationsautoren, die sie kopieren und in ihre eigenen AsciiDoc-Dokumente einfügen können.

In diesem Abschnitt verwenden wir die folgende Repository-Struktur als Beispiel:

Beispiel für die Struktur eines Dokumentationsrepositories
📄 antora.yml (1)
📂 modules
  📂 ROOT
    📂 pages
      📄 index.adoc
      📄 another-page.adoc
      📂 sub-dir
        📄 rules.adoc
  📂 council
    📂 pages
      📄 guiding-policy.adoc
1 Definiert die Dokumentationskomponente als Testmodul (Attribut name)

Gleiches Repository

Verwenden Sie den lokalen Pfad relativ zum Verzeichnis pages im selben Modul.

Link zu einer Seite auf der obersten Ebene
xref:another-page.adoc
Link zu einer Seite in einem Unterverzeichnis von pages
xref:sub-dir/rules.adoc

Ähnlich wie ein interner Link, aber mit einem Doppelpunkt (:) als Trennzeichen zwischen den Modulnamen. Wenn Sie sich nicht sicher sind, ob Sie dies benötigen, ist es wahrscheinlich nicht nötig! Mehrere Module im selben Repository sind in der Fedora-Dokumentation derzeit kein gängiges Szenario.

Beispiel 1
xref:council:guiding-policy.adoc

Verlinken Sie eine andere Fedora-Dokumentationsseite in einem anderen Repository. Beachten Sie, dass Sie unbedingt das Feld name aus der Datei antora.yml des anderen Repositorys verwenden müssen, sonst funktioniert es nicht. Falls das Zielmodul den Namen ROOT trägt, können Sie den Namen weglassen, benötigen aber trotzdem den zusätzlichen Doppelpunkt (:).

Beispiel 1, beide Links sind äquivalent
xref:testmodul::andere-seite.adoc
xref:testmodul:ROOT:andere-seite.adoc
Beispiel 2
xref:test-module:council:guiding-policy.adoc

URL-Weiterleitungen

Sie können eine Weiterleitung von einer alten Seite zu einer neuen Seite erstellen, indem Sie das Attribut page-aliases`https://docs.antora.org/antora/latest/page/page-aliases/[`page-aliases] verwenden. Die Syntax ist dieselbe wie für xref-Links.

Beispiel 1. In new-page.adoc
= Seitentitel
:page-aliases: old-page.adoc

Sie können auch eine Weiterleitung von einem anderen Modul oder einer anderen Komponente aus erstellen.

Beispiel 2. In new-page.adoc
= Seitentitel
:page-aliases: test-module:council:removed-page.adoc

Syntax-Hervorhebung

Sie können Syntaxhervorhebung zu jedem Quellcodeblock hinzufügen, indem Sie das Attribut language festlegen.

Beispiel für das Festlegen des Quellsprachenattributs für einen Codeblock
[,yaml]
----
output:
  clean: true
  dir: ./public
  destinations:
  - provider: archive
----
Beispiel eines gerenderten Codeblocks mit einem solchen Attribut
output:
  clean: true
  dir: ./public
  destinations:
  - provider: archive

Die Liste der unterstützten Sprachen finden Sie in highlight.bundle.js in der Fedora Docs UI.

Datentabellen

Sie können eine reguläre Tabelle mithilfe des datatable-Rollenattributs in eine Datentabelle konvertieren. Datentabellen bietet Filter- und Sortierfunktionen.

Beispiel für die Definition einer Datentabelle
|===
[.datatable]
|colA | colB | colC | colD

| yyy | 123 | zzz | 28%
| bbb | 242 | aaa | 42%
| ddd | 8874 | yyy | 99%
| ccc | 9 | ttt | 2%
| aaa | 987 | www | 18%
|===

.Rendered DataTable [.datatable]

colA

colB

colC

colD

yyy

123

zzz

28%

bbb

242

aaa

42%

ddd

8874

yyy

99%

ccc

9

ttt

2%

aaa

987

www

18%

Zusätzliche Rollen können verwendet werden, um Datentabellen-Funktionen hinzuzufügen:

  • dt-search: Suchfeld hinzufügen

  • dt-paging: Paginierung hinzufügen

Sie können das Styling auch mithilfe der eingebauten DataTables-Klassen ändern, z.B. mit display oder compact.

Beispiel für die Verwendung zusätzlicher Optionen
|===
[.datatable.dt-search.display]
|colA | colB | colC | colD

| yyy | 123 | zzz | 28%
| bbb | 242 | aaa | 42%
| ddd | 8874 | yyy | 99%
|===

Ein Beispiel für die reale Verwendung von DataTables finden Sie in der Dokumentation Not-Allowed Licenses.

Reiterleiste

Sie können eine Reihe von Reitern erstellen, um den Dokumentationsinhalt in einem Block zu organisieren.

Beispiel für die Definition einer Reiterleiste [,asciidoc]
[tabs]
====
Reiter A:: Inhalt von Reiter A.

Reiter B::
+
Inhalt von Reiter B.

Reiter C::
+
--
Inhalt von Reiter C.

Enthält mehr als einen Block.
--
====
sich ergebende Reiterleiste

  • Tab A

  • Reiter B

  • Reiter C

Inhalt von Reiter A.

Inhalt von Reiter B.

Inhalt von Reiter C.

Enthält mehr als einen Block.

Weitere Informationen zu Reitern finden Sie in der Asciidoctor Tabs-Erweiterung unter https://github.com/asciidoctor/asciidoctor-tabs.

Inhaltsverzeichnis

Am rechten Rand jeder Seite wird automatisch ein Inhaltsverzeichnis generiert.

WICHTIG: Das Attribut :toc: muss nicht hinzugefügt werden, da dadurch ein doppeltes Inhaltsverzeichnis im Dokument erstellt werden würde.

Das Inhaltsverzeichnis auf der rechten Seite zeigt standardmäßig nur Titelebenen bis Ebene 2 an. Diese Einstellung kann mit dem Attribut page-toclevels geändert werden.

= Seitentitel
:page-toclevels: 3

Paginierung

Wenn Sie mehrere Seiten zum selben Thema haben, könnte die Paginierung für Sie interessant sein. + Die Paginierung ermöglicht es dem Leser, mithilfe von Navigationslinks am Seitenende einfach zwischen den Seiten zu navigieren.

Diese Option wird durch das Attribut page-pagination aktiviert.

= Seitentitel
:page-pagination:

Auf dieser Seite können Sie ein Live-Beispiel sehen.

UI-Makro für Knöpfe und Menüs

Um eine einheitliche Darstellung von Knöpfen, Tastenfolgen oder Menüpunkten (Pfaden) zu gewährleisten, kommunizieren Knopf- und Menü-UI-Makros dem Leser, welche Aktionen er ausführen muss.

WICHTIG: Obwohl dieses Attribut als experimentell bezeichnet wird, gelten die UI-Makros als stabiles Feature von AsciiDoc und werden in den neuesten bearbeiteten Quick Docs verwendet.

Diese Option wird durch das Attribut experimental aktiviert.

= Seitentitel
:experimental:

Beispiel für die Definition des Knopf-UI-Makros

. Click btn:[Create].

. Choose a passphrase that is strong but also easy to remember in the dialog that is displayed.

. Click btn:[OK] and the key is created.

Beispiel für die Definition des Menü-UI-Makros

To save the file, select menu:File[Save].

Select menu:View[Zoom > Reset] to reset the zoom level to the default setting.

Bewährte Vorgehensweise

Ein paar Empfehlungen zum Schreiben neuer Seiten oder zum Bearbeiten bestehender Seiten.

Kopfzeilen des Dokuments

Alle Seiten müssen mit einem Titel der Ebene 1 beginnen. [,asciidoc]

= Seitentitel

Optional können Sie authors- und review-Metadaten hinzufügen.

Beispiel 1 - Autor- und Revisionsinformation
= Seitentitel
Ben Cotton; Peter Boy; Petr Bokoc 2.0, 2022-11-26: fix for F37

Sie können die Versionsnummer weglassen, falls Sie diese Information nicht benötigen.

Beispiel 2 - Revisionsinformation ohne Version
= Seitentitel
Francois Andrieu 2022-12-10: Added revision metadata example

Diese Metadaten sind zwar optional, aber versuchen Sie zumindest das Revisionsdatum anzugeben, damit die Leser wissen, wie aktuell die Seite ist.

Beispiel 3 - Nur Revisionsdatum
= Seitentitel
Fedora Documentation Team 2022-12-10

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