Skip to main content
Contributor's Guide
Die deutsche Sprachversion wurde als Serviceleistung für Sie durch maschinelle Übersetzung erstellt. Bei eventuellen Unstimmigkeiten hat die englische Sprachversion Vorrang.

AsciiDoc Referenz

Beitragende
PDFs

AsciiDoc ist eine leichte Markup-Sprache, ähnlich wie Markdown. Wir entschieden uns für AsciiDoc gegenüber Standard Markdown, weil es mehr Out-of-Box-Funktionen bietet. Zwar ist es noch leistungsstärker, aber dennoch einfach zu bedienen. Lesen Sie die folgenden Abschnitte, um in AsciiDoc zu schreiben.

Siehe "AsciiDoctor Benutzerhandbuch" Für weitere Hilfe.

Die Grundlagen

Du musst ein paar Dinge wissen, um einfache doc-Updates beisteuern zu können.

Überschriften

= Page title
== Level 1 section
=== Level 2 section
==== Level 3 section
===== Level 4 section

Sie können nur einen Seitentitel haben, aber Sie können mehrere Abschnittstitel haben. Beispielsweise können Sie drei Abschnitte der Stufe 1 enthalten, die die Abschnitte der Ebene 2 und 3 enthalten:

= Page title
== Level 1 section
=== Level 2 section
== Level 1 section
== Level 1 section
=== Level 2 section
==== Level 3 section

Fett formatierter Text

*Text*

Kursiver Text

_Text_

Aufzählungslisten

* Item 1
+
Continuation text for the previous list item.

* Item 2
** Item 2a

* Item 3
Tipp Der + ist eine Listenweiterführung. Der Text wird mit dem Listenelement inline gespeichert. Das Weglassen des + wirkt sich auf die Formatierung dieser Zeile aus.

Markierte Listen

Item 1::
Description 1

Item 2::
Description 2

Oder

[horizontal]
Item 1::
Description 1

Item 2::
Description 2

Wenn Sie über Punkt 1 [horizontal] hinzufügen, werden die Beschriftung und die Beschreibung in derselben Zeile angezeigt. Das funktioniert gut, wenn man sehr kurze Beschreibungen hat.

Beispiel ohne [waagerecht]

Punkt 1

Warenbezeichnung 1

Punkt 2

Warenbezeichnung 2

  • Beispiel mit [waagerecht]*

Punkt 1

Warenbezeichnung 1

Punkt 2

Warenbezeichnung 2

Schritte

.Steps

. Step 1

. Step 2
+
Info for step 2

. Step 3
.. Step 3a
.. Step 3b

. Step 4
Tipp Der + ist eine Listenweiterführung. Der Text wird mit dem Listenelement inline gespeichert. Das Weglassen des + wirkt sich auf die Formatierung dieser Zeile aus.

Bilder

image:file.png["alt text"]

alt-Text bedeutet alternativer Text. Es beschreibt das Bild, das auf der Seite angezeigt wird. Der primäre Gebrauch ist für Benutzer mit Sehbehinderung, die Bildschirmleser verwenden.

Zwei Anmerkungen:

  1. Am besten fügen sie alt-Text in Anführungszeichen ein, weil Satzzeichen wie Kommas die Fähigkeit beeinflussen können, den Inhalt von AsciiDoc in HTML zu transformieren.

  2. Der "AsciiDoctor docs" Geben Sie an, dass Block Images auf ihrer eigenen Zeile mit zwei Doppelpunkte liegen sollte: image::file.png

    Aber wir verwenden lieber einen Doppelpunkt, wie oben gezeigt. Mit einem Doppelpunkt hat das gleiche Ergebnis und es funktioniert besser mit unseren internen Tools.

Videos

Gehostet auf YouTube:

video::id[youtube]

Lokal in GitHub gehostet:

video::file.mp4

Die Syntax, die Sie verwenden sollten, hängt davon ab, mit welchem Link Sie verbunden sind:

url[link text^]

Der ^ öffnet den Link in einer neuen Browser-Registerkarte.

<<section_title>>

Beispiel:

For more details, see <<Headings>>.

Der Linktext kann etwas anderes als der Abschnittstitel sein:

<<section_title,Different link text>>

Beispiel:

<<Headings,Learn the syntax for headings>>.

Die Datei muss sich im selben GitHub-Repository befinden:

link:<file_name>.html[Link text]

Um direkt mit einem Abschnitt in der Datei zu verknüpfen, fügen Sie einen Hash (#) und den Titel des Abschnitts hinzu:

link:<file_name>.html#<section-name-using-dashes-and-all-lower-case>[Link text]

Beispiel:

link:style.html#use-simple-words[Use simple words]

Hinweise, Tipps und Hinweise

Möglicherweise möchten Sie auf bestimmte Aussagen aufmerksam machen, indem Sie Notizen, Tipps oder Vorsichtshinweise verwenden. Formatieren Sie sie wie folgt:

NOTE: text

TIP: text

CAUTION: text

Verwenden Sie jedes dieser sparsam. Sie möchten keine Seiten erstellen, die voller Notizen und Tipps sind. Sie werden weniger bedeutungsvoll, wenn Sie es tun.

So sieht jeder aus, als der AsciiDoc-Inhalt in HTML umgewandelt wird:

Hinweis Dies ist eine Notiz. Es enthält zusätzliche Informationen, die ein Leser wissen muss.
Tipp Ein Tipp bietet nützliche Informationen, die einem Benutzer dabei helfen können, etwas zu tun oder etwas zu verstehen.
Achtung Eine Vorsicht empfiehlt dem Leser, vorsichtig zu handeln. Verwenden Sie dies in seltenen Fällen.

Fortschrittliche Sachen

Wenn Sie neue Inhalte verfassen, sollten Sie diesen Abschnitt über einige Details lesen.

Dokumentüberschriften

Jede AsciiDoc-Datei enthält zwei Headertypen. Die erste ist für GitHub und die zweite ist für AsciiDoctor, das Verlags-Tool, das den AsciiDoc-Inhalt in HTML verwandelt.

Der GitHub Header ist der erste Satz von Inhalten in der .Adoc-Datei. Es muss Folgendes enthalten:

---
sidebar: sidebar
permalink: <file_name>.html
keywords: keyword1, keyword2, keyword3, keyword4, keyword5
summary: "A summary."
---

Die Suchbegriffe und die Zusammenfassung wirken sich direkt auf die Suchergebnisse aus. Die Zusammenfassung selbst wird in den Suchergebnissen angezeigt. Sie sollten sicherstellen, dass es benutzerfreundlich ist. Als Best Practice empfiehlt es sich, die Zusammenfassung Ihren Lead-Absatz zu spiegeln.

Tipp Am besten sollte die Zusammenfassung in Anführungszeichen eingeschlossen werden, da Satzzeichen wie Doppelpunkte die Fähigkeit beeinflussen können, den Inhalt von AsciiDoc in HTML zu transformieren.

Die nächste Kopfzeile geht direkt unter den Dokumenttitel (siehe Überschriften). Diese Kopfzeile sollte Folgendes enthalten:

:hardbreaks:
:nofooter:
:icons: font
:linkattrs:
:imagesdir: ./media/

Sie müssen keine der Parameter in dieser Überschrift berühren. Fügen Sie es einfach ein und vergessen Sie es.

Lead-Absatz

Der erste Absatz, der unter dem Dokumenttitel angezeigt wird, sollte die folgende Syntax direkt darüber enthalten:

[.lead]
This is my lead paragraph for this content.

[.Lead] wendet die CSS-Formatierung auf den Lead-Absatz an, der ein anderes Format hat als der darauf folgende Text.

Tabellen

Folgende Syntax ist für eine Basistabelle erforderlich:

[cols=2*,options="header",cols="25,75"]
|===
| heading column 1
| heading column 2
| row 1 column 1 | row 1 column 2
| row 2 column 1 | row 2 column 2
|===

Es gibt many Möglichkeiten, eine Tabelle zu formatieren. Siehe "AsciiDoctor Benutzerhandbuch" Für weitere Hilfe.

Tipp Wenn eine Zelle formatierte Inhalte wie Aufzählungslisten enthält, sollten Sie am besten ein „A“ in die Spaltenüberschrift hinzufügen, um die Formatierung zu aktivieren. Beispiel: [Cols=„2,2,4a“ options=„Header“]

"Weitere Tabellenbeispiele finden Sie in der Kurzreferenz AsciiDoc Syntax".

Aufgabenüberschriften

Wenn Sie erklären, wie Sie eine Aufgabe ausführen, können Sie einleitende Informationen angeben, bevor Sie zu den Schritten gelangen. Und Sie müssen möglicherweise sagen, was nach dem Durchführen der Schritte zu tun ist. Wenn Sie das tun, ist es am besten, diese Informationen mit Kopfzeilen zu organisieren, die das Scannen ermöglichen.

Verwenden Sie bei Bedarf die folgenden Überschriften:

Was Sie benötigen

Die Informationen, die der Benutzer benötigt, um die Aufgabe abzuschließen.

Über diese Aufgabe

Einige zusätzliche kontextbezogene Informationen, die der Benutzer über diese Aufgabe wissen muss.

Schritte

Die einzelnen Schritte zum Abschließen der Aufgabe.

Was kommt als Nächstes?

Was der Benutzer als Nächstes tun sollte.

Jede dieser sollte eine enthalten. Direkt vor dem Text, wie so:

.What you'll need
.About this task
.Steps
.What's next?

Diese Syntax wendet fett formatierte Texte in einer größeren Schrift an.

Befehlssyntax

Schließen Sie bei Eingabe des Befehls den Befehl in ` an, um die Schriftart „monospace“ anzuwenden:

`volume show -is-encrypted true`

So sieht das aus:

volume show -is-encrypted true

Verwenden Sie für Beispiele für die Befehlsausgabe oder den Befehl die folgende Syntax:

----
cluster2::> volume show -is-encrypted true

Vserver  Volume  Aggregate  State  Type  Size  Available  Used
-------  ------  ---------  -----  ----  -----  --------- ----
vs1      vol1    aggr2     online    RW  200GB    160.0GB  20%
----

Mit den vier Strichen können Sie separate Textzeilen eingeben, die zusammen angezeigt werden. Hier ist das Ergebnis:

cluster2::> volume show -is-encrypted true

Vserver  Volume  Aggregate  State  Type  Size  Available  Used
-------  ------  ---------  -----  ----  -----  --------- ----
vs1      vol1    aggr2     online    RW  200GB    160.0GB  20%

Variablentext

In Befehlen und Befehlsausgabe muss Variablentext in Unterstriche eingeschlossen werden, um kursiv anzuwenden.

`vserver nfs modify -vserver _name_ -showmount enabled`

So sieht der Befehl und der Variablentext aus:

vserver nfs modify -vserver name -showmount enabled

Hinweis Unterstriche werden derzeit nicht durch das Markieren von Code-Syntax unterstützt.

Hervorhebung der Code-Syntax

Das Hervorheben der Code-Syntax bietet eine entwicklerorientierte Lösung zur Dokumentation der gängigsten Sprachen.

Ausgabebeispiel 1

POST https://netapp-cloud-account.auth0.com/oauth/token
Header: Content-Type: application/json
Body:
{
              "username": "<user_email>",
              "scope": "profile",
              "audience": "https://api.cloud.netapp.com",
              "client_id": "UaVhOIXMWQs5i1WdDxauXe5Mqkb34NJQ",
              "grant_type": "password",
              "password": "<user_password>"
}

Ausgabebeispiel 2

[
    {
        "header": {
            "requestId": "init",
            "clientId": "init",
            "agentId": "init"
        },
        "payload": {
            "init": {}
        },
        "id": "5801"
    }
]

Unterstützte Sprachen

  • Bash

  • Curl

  • https

  • json

  • powershell

  • Puppet

  • python

  • yaml

  • Umsetzung*

Kopieren Sie die folgende Syntax und fügen Sie dann eine unterstützte Sprache und den Code hinzu:

[source,<language>]
<code>

Beispiel:

[source,curl]
curl -s https:///v1/ \
-H accept:application/json \
-H "Content-type: application/json" \
-H api-key: \
-H secret-key: \
-X [GET,POST,PUT,DELETE]

Wiederverwendung von Inhalten

Wenn Sie einen Teil von Inhalten haben, der auf verschiedenen Seiten wiederholt wird, können Sie ihn einfach einmal schreiben und auf diesen Seiten wiederverwenden. Eine Wiederverwendung ist aus demselben Repository und über mehrere Repositorys hinweg möglich. Und so funktioniert's.

  1. Erstellen Sie einen Ordner in Ihrem Repository namens_include

    "Sehen Sie sich beispielsweise das Cloud Tiering Repository an".

  2. Fügen Sie eine Adoc-Datei in diesem Ordner hinzu, die den Inhalt enthält, den Sie verwenden möchten.

    Es kann sich um einen Satz, eine Liste, eine Tabelle, einen oder mehrere Abschnitte usw. handelt. Fügen Sie nichts anderes in die Datei ein - keine Kopfzeilen oder irgendetwas.

  3. Rufen Sie nun die Dateien auf, in denen Sie diesen Inhalt wiederverwenden möchten.

  4. Wenn Sie den Inhalt aus dem same GitHub-Repository erneut verwenden, verwenden Sie die folgende Syntax in einer Zeile allein:

    include::_include/<filename>.adoc[]

    Beispiel:

     include::_include/s3regions.adoc[]
. Wenn Sie den Inhalt in einem _different_-Repository wiederverwenden, verwenden Sie die folgende Syntax in einer Zeile allein:
    include::https://raw.githubusercontent.com/NetAppDocs/<reponame>/main/_include/<filename>.adoc[]

    Beispiel:

    include::https://raw.githubusercontent.com/NetAppDocs/cloud-tiering/main/_include/s3regions.adoc[]

Das ist alles.

Wenn Sie mehr über die Richtlinie einschließlich "Sehen Sie sich das AsciiDoctor Benutzerhandbuch an".