Markdown zum Schreiben von technischer Dokumentation verwenden

Die technischen Adobe-Dokumentationsartikel werden in einer einfachen Markup-Sprache namens Markdown geschrieben, die einfach zu lesen und zu lernen ist.

Wenn wir Adobe Docs-Inhalt in GitHub speichern, kann eine Version von Markdown mit dem Namen GitHub Flavored Markdown (GFM) verwendet werden, die zusätzliche Funktionen für allgemeine Formatierungsanforderungen bietet. Außerdem erweiterte Adobe Markdown auf verschiedene Arten, um bestimmte Hilfefunktionen wie Anmerkungen, Tipps und eingebettete Videos zu unterstützen.

Markdown-Grundlagen

Überschriften

Um eine Überschrift zu erstellen, verwenden Sie ein Hash-Zeichen (#) am Anfang einer Zeile:

# This is level 1 (article title)
## This is level 2
### This is level 3
#### This is level 4
##### This is level 5

Einfacher Text

Ein Absatz erfordert keine spezielle Syntax in Markdown.

Um Text fett zu formatieren, schließen Sie ihn in doppelte Sternchen ein. Um Text kursiv zu formatieren, schließen Sie ihn in einfache Sternchen ein:

   This text is **bold**.
   This text is *italic*.
   This text is both ***bold and italic***.

Um Markdown-Formatierungszeichen zu ignorieren, verwenden Sie \ vor dem Zeichen:

This is not \*italicized\* type.

Nummerierte Listen und Aufzählungslisten

Um nummerierte Listen zu erstellen, beginnen Sie eine Zeile mit 1. oder 1), aber mischen Sie die Formate nicht in derselben Liste. Sie müssen die Zahlen nicht speziell angeben. GitHub erledigt das für Sie.

1. This is step 1.
1. This is the next step.
1. This is yet another step, the third.

Angezeigt:

  1. This is step 1.
  2. This is the next step.
  3. This is yet another step, the third.

Um Listen mit Aufzählungszeichen zu erstellen, beginnen Sie eine Zeile mit „*“, „-“ oder „+“, aber mischen Sie die Formate nicht in derselben Liste. (Mischen Sie Aufzählungsformate wie * und + nicht innerhalb desselben Dokuments.)

* First item in an unordered list.
* Another item.
* Here we go again.

Angezeigt:

  • First item in an unordered list.
  • Another item.
  • Here we go again.

Sie können auch Listen in Listen einbetten und Inhalte zwischen Listenelementen hinzufügen.

1. Set up your table and code blocks.
1. Perform this step.

   ![screen](/docs/contributor/assets/adobe_standard_logo.png?lang=de)
1. Make sure that your table looks like this: 

   | Hello | World |
   |---|---|
   | How | are you? |  
1. This is the fourth step.

   >[!NOTE]
   >
   >This is note text.

1. Do another step.

Angezeigt:

  1. Set up your table and code blocks.

  2. Perform this step.

    Bildschirm

  3. Make sure that your table looks like this:

    Hello World
    How are you?
  4. This is the fourth step.

    HINWEIS

    This is note text.

  5. Do another step.

Tabellen

Tabellen sind nicht Teil der Markdown-Kernspezifikation, doch Adobe unterstützt sie in einem gewissen Maße. Markdown unterstützt keine Listen mit mehreren Zeilen in Zellen. Es empfiehlt sich, mehrere Zeilen in Tabellen zu vermeiden. Sie können Tabellen mit dem Strichzeichen (|) erstellen, um Spalten und Zeilen abzutrennen. Mit Bindestrichen wird die Kopfzeile der einzelnen Spalten erstellt, während die Striche die Spalten trennen. Fügen Sie vor der Tabelle eine leere Zeile ein, damit sie korrekt angezeigt wird.

| Header | Another header | Yet another header |
|--- |--- |--- |
| row 1 | column 2 | column 3 |
| row 2 | row 2 column 2 | row 2 column 3 |

Angezeigt:

Header Another header Yet another header
row 1 column 2 column 3
row 2 row 2 column 2 row 2 column 3

Einfache Tabellen funktionieren in Markdown angemessen. Tabellen, die mehrere Absätze oder Listen in einer Zelle enthalten, sind jedoch schwer zu bearbeiten. Für solche Inhalte empfehlen wir ein anderes Format, z. B. Überschriften und Text.

Weitere Informationen zum Erstellen von Tabellen finden Sie unter:

Die Markdown-Syntax für einen Inline-Link besteht aus dem [link text]-Teil, der den Hyperlinktext enthält, gefolgt vom (file-name.md)-Teil, der die URL oder den Dateinamen enthält, mit der/dem verlinkt wird:

[link text](file-name.md)

[Adobe](https://www.adobe.com)

Angezeigt:

Adobe

Verwenden Sie relative Links für Verknüpfungen zu Artikeln (Querverweise) im Repository. Sie können alle relativen Link-Operanden verwenden, z. B. ./ (aktuelles Verzeichnis), …/ (ein Verzeichnis zurück) und …/…/ (zwei Verzeichnisse zurück).

See [Overview example article](../../overview.md)

Weitere Informationen zur Verknüpfung finden Sie im Artikel Links in diesem Handbuch zur Verknüpfungssyntax.

Bilder

![Adobe Logo](/docs/contributor/assets/adobe_standard_logo.png?lang=de)

Angezeigt:

Adobe Logo

Hinweis: Erstellen Sie für Bilder, die nicht lokalisiert werden sollen, einen separaten do-not-localize Ordner im Ordner „Assets“. Normalerweise werden dort Bilder ohne Text oder Bilder mit reinen Beispielinhalten abgelegt. Dadurch wird jegliches „Rauschen“ aus dem Ordner „Assets“ entfernt und die Anzahl der Fragen reduziert.

Codeblöcke

Markdown unterstützt die Platzierung von Codeblöcken sowohl in einem Satz als auch als separater „abgegrenzter“ Block zwischen Sätzen. Weitere Informationen finden Sie unter Native Markdown-Unterstützung für Codeblöcke.

Verwenden Sie Backticks ( ` ), um Inline-Code-Stile in einem Absatz zu erstellen. Um einen bestimmten mehrzeiligen Code-Block zu erstellen, fügen Sie vor und nach dem Code-Block (in Markdown als „abgegrenzter Code-Block“ und in Adobe Experience Manager einfach als „Code-Block“ bezeichnet) drei Backticks (```) vor und nach dem Code-Block ein. Fügen Sie bei abgegrenzten Codeblöcken die Codesprache nach dem ersten Satz Backticks ein, sodass Markdown die Codesyntax korrekt hervorhebt. Beispiel: ```javascript

Beispiele:

This is `inline code` within a paragraph of text.

Angezeigt:

This is inline code within a paragraph of text.

Dies ist ein abgegrenzter Codeblock:

function test() {
 console.log("notice the blank line before this function?");

Benutzerspezifische Markdown-Erweiterungen

Adobe-Artikel verwenden Standard-Markdown für die meisten Artikelformatierungen wie Absätze, Links, Listen und Überschriften. Für eine reichhaltigere Formatierung können Artikel erweiterte Markdown-Funktionen verwenden, z. B.:

  • Hinweisblöcke
  • Eingebettete Videos
  • Nicht lokalisieren
  • Komponenteneigenschaften, z. B. Zuweisen einer anderen Kopfzeilen-ID zu einer Kopfzeile

Verwenden Sie das Markdown-Blockanführungszeichen (>) am Anfang jeder Zeile, um eine erweiterte Komponente wie einen Hinweis anzubinden. Wenn Sie Unterkomponenten in Komponenten verwenden müssen, fügen Sie für diesen Unterkomponentenabschnitt eine zusätzliche Ebene von Blockanführungszeichen (> >) hinzu. Beispielsweise sollte ein HINWEIS in einem DONOTLOCALIZE-Abschnitt mit > > beginnen.

Einige gängige Markdown-Elemente wie Kopfzeilen und Codeblöcke umfassen erweiterte Eigenschaften. Wenn Sie die Standardeigenschaften ändern müssen, fügen Sie die Parameter in geschweiften Klammern /{ /} nach der Komponente hinzu. Erweiterte Eigenschaften werden im Kontext beschrieben.

Hinweisblöcke

Sie können aus vier Arten von Hinweisblöcken wählen, um die Aufmerksamkeit auf bestimmte Inhalte zu lenken:

  • [!NOTE]
  • [!TIP]
  • [!IMPORTANT]
  • [!CAUTION]
  • [!WARNING]
  • [!ADMINISTRATION]
  • [!AVAILABILITY]
  • [!PREREQUISITES]

Im Allgemeinen sollten Hinweise sparsam verwendet werden, da sie stören können. Obwohl sie auch Codeblöcke, Bilder, Listen und Links unterstützen, sollten Sie Ihre Hinweise einfach und geradlinig halten.

>[!NOTE]
>
>This is a standard NOTE block.

Angezeigt:

HINWEIS

This is a standard NOTE block.

>[!TIP]
>
>This is a standard tip.

Angezeigt:

TIPP

This is a standard tip.

Videos

Eingebettete Videos werden nicht nativ in Markdown gerendert, Sie können aber diese Markdown-Erweiterung verwenden.

>[!VIDEO](https://video.tv.adobe.com/v/29770/?quality=12)

Angezeigt:

Mehr wie dieses

Die Komponente „Mehr wie dieses“ in AEM wird am Ende eines Artikels angezeigt. Es werden zugehörige Links angezeigt. Wenn der Artikel gerendert wird, kann er wie Ebene-2-Kopfzeilen (##) formatiert werden, ohne dem Mini-Inhaltsverzeichnis hinzugefügt zu werden.

>[!Related Articles]
>* [Article 1](https://helpx.adobe.com/de/support/analytics.html)
>* [Article 2](https://helpx.adobe.com/de/support/audience-manager.html)

Angezeigt:

UICONTROL und DNL

Alle unsere Markdown-Hilfeinhalte werden zunächst durch maschinelle Übersetzung lokalisiert. Wenn die Hilfe noch nie lokalisiert wurde, behalten wir die maschinelle Übersetzung bei. Wenn der Hilfeinhalt jedoch in der Vergangenheit lokalisiert wurde, fungiert der maschinell übersetzte Inhalt als Platzhalter, während der Inhalt manuell übersetzt wird.

``

Während der maschinellen Übersetzung werden Elemente, die mit ``-Tags versehen sind, für die entsprechende Übersetzung mit einer lokalen Anpassungsdatenbank abgeglichen. Für den Fall, dass die Benutzeroberfläche nicht lokalisiert ist, ermöglicht dieses Tag dem System, die Benutzeroberflächenreferenz in Englisch für die jeweilige Sprache zu belassen (z. B. Analytics-Referenzen in Italienisch).

Beispiel:

  1. Navigieren Sie zum Bildschirm Run Process.
  2. Wählen Sie File > Print > Print All, um alle Dateien auf Ihrem Server zu drucken.
  3. Das Dialogfeld Processing Rules wird angezeigt.

Quelle:

1. Go to the **Run Process** screen.
1. Choose **File > Print > Print All** to print all the files on your server.
1. The Processing Rules dialog box appears.

Hinweis: Von den drei Tagging-Optionen ist dies die wichtigste, um eine hohe Qualität zu erzielen, und sie ist obligatorisch.

[!DNL]

In der Regel wird eine „Nicht übersetzen“-Liste verwendet, um den maschinellen Übersetzungsprogrammen mitzuteilen, was auf Englisch bleiben soll. Zu den häufigsten Begriffen gehören lange Lösungsnamen wie „Adobe Analytics“, „Adobe Campaign“ und „Adobe Target“. Es kann jedoch vorkommen, dass zwingend Englisch genutzt werden muss, weil der betreffende Begriff auf eine bestimmte oder allgemeine Weise verwendet werden kann. Am naheliegendsten sind Kurzbezeichnungen für die Lösungen wie „Analytics“, „Campaign“, „Target“ usw. Es wäre für eine Maschine schwierig zu verstehen, dass es sich um Lösungsnamen und nicht um allgemeine Begriffe handelt. Das Tag kann auch für Namen/Funktionen von Drittanbietern verwendet werden, die immer in Englisch bleiben, oder für kürzere Textabschnitte wie eine Wortgruppe oder einen Satz, die in Englisch bleiben müssen.

Beispiel:

  • Mit Target können Sie A/B-Tests erstellen, um die optimale
  • Adobe Analytics ist eine leistungsstarke Lösung zur Erfassung von Analysen auf Ihrer Website. Analytics kann Ihnen auch bei Berichten helfen, um diese Daten leicht zu verarbeiten.

Quelle:

* With Target, you can create A/B tests to find the optimal 
* Adobe Analytics is a powerful solution to collect analytics on your site. Analytics can also help you with reporting to easily digest that data.

Gotchas und Fehlerbehebung

Alternativtext

Alternativtext, der Unterstriche enthält, wird nicht richtig gerendert. Statt dies zu verwenden:

![Settings_Step_2](/assets/settings_step_2.png)

Empfehlen wir die Verwendung von Bindestrichen (-) anstelle von Unterstrichen (_) in Dateinamen.

![Settings-Step-2](/assets/settings-step-2.png)

Apostrophe und Anführungszeichen

Wenn Sie Text in einen Markdown-Bearbeiter kopieren, kann der Text „smarte“ (geschweifte) Apostrophe oder Anführungszeichen enthalten. Diese müssen kodiert oder in einfache Apostrophe oder Anführungszeichen geändert werden. Andernfalls erhalten Sie korrupte Zeichen wie die folgenden, wenn die Datei veröffentlicht wird: It’s

Im Folgenden finden Sie die Kodierungen für die „smarten“ Versionen dieser Interpunktionszeichen:

  • Anführungszeichen links (öffnend): “
  • Anführungszeichen rechts (schließend): ”
  • Rechts (schließend) einfaches Anführungszeichen oder Apostroph: ’
  • Links (öffnend) einfaches Anführungszeichen (selten verwendet): ‘

Spitze Klammern

Wenn Sie spitze Klammern im Text (nicht im Code) in Ihrer Datei verwenden, zum Beispiel, um einen Platzhalter anzugeben, müssen Sie die spitzen Klammern manuell kodieren. Andernfalls wird in Markdown davon ausgegangen, dass sie ein HTML-Tag sein sollen.

Kodieren Sie beispielsweise <script name> als &lt;script name&gt;

Et-Zeichen in Titeln

Et-Zeichen (&) sind in Titeln nicht zulässig. Verwenden Sie stattdessen „und“ oder die &amp;-Kodierung.

Siehe auch

Markdown-Ressourcen

Auf dieser Seite