Markdown ermöglicht das semantische Auszeichnen von Dokumenten, ohne dabei auf “magische Tools” wie WYSIWYG-Editoren angewiesen zu sein, welche einem die Kontrolle über den schlussendlich generierten Code rauben (welcher oftmals katastrophal ist). Alle Anweisungen werden in einer sauberen, recht intuitiven und somit sehr einfachen Syntax geschrieben (siehe nachfolgendes Markdown Beispiel).

Markdown Beispiel

# Dies ist eine Überschrift 1

## Dies ist eine Überschrift 2

Dies ist ein Paragraph.

Dies ist ein weiterer Paragraph.__
Zwei Leerschläge am Ende einer Zeile bewirken einen harten Umbruch.

Dieser Paragraph hat einen [Link](http://example.com).

Dieser Paragraph hat ein Bild: ![Alternativtext](image.jpg).

- Erster Eintrag einer ungeordneten Liste
- Zweiter Eintag
    - Verschachtelte Liste!
    - Noch ein Eintrag!
- Dritter Eintrag

1. Erster Eintrag einer geordneten Liste
1. Zweiter Eintrag (die verwendete Zahl hat keinen Einfluss)

| Artikel   | Menge (zentriert) | Value (rechtsbündig) |
| --------- | :---------------: | --------------------:|
| Computer  | 1                 | $1600                |
| Phone     | 3                 | $12                  |

Einige weitere wichtige Hinweise:

• Keine Doppelpunkte am Ende einer Überschrift!
• Jegliche Wert-Angaben in Backticks! Also bspw. auch em oder 4.5:1!
• Tastaturkürzel so angeben: Strg+a
• Linktexte ohne http://!

Formatieren von Code-Blöcken

Mittels Backticks kann Code inline formatiert werden: alt="". Entweder muss Block-Code mit 4 Leerzeichen eingerückt werden (jede Zeile), oder der Block mit 3 Backticks beginnen und enden.

```
h1 My Details
  h2 My address
  h2 Availability via...
  h2 Orders and contacts
    ...etc...
```

Verfügbare Überschriften-Ebenen

Laut HTML-Standard sind nur sechs Überschriften verfügbar. Markdown hält sich strikt an diese Vorgabe. Dies bedeutet, dass darauf geachtet werden muss, dass diese Tiefe nicht überschritten wird!

Unser generierter Bericht braucht alleine schon durch die Anlehnung an die WCAG-Struktur mehrere Levels auf. Folgende Hinweise sollen beherzigt werden, um die Tiefe von sechs Ebenen nicht zu überschreiten:

• Erfolgskriterien können theoretisch beliebig tief verschachtelt werden. Es darf aber bloss eine weitere Ebene verwendet werden:
  • Beispiel: “Formular-Beziehungen” (4. Stufe) innerhalb von “1.3.1 Info und Beziehungen” (3. Stufe)
  • Eine 5. Stufe (z.B. “Checkboxen und Radiobuttons” unter “Formular-Beziehungen”) ist nicht erlaubt!
  • Beim Verwenden von Überschriften in mehrzeiligen Textfeldern muss zur Vorsicht angehalten werden:
    • Am besten allgemein nicht zu tief verschachteln
    • Mehrzeilige Textfelder von Befunden sollen keinerlei Überschriften enthalten (ein Befund einer Anforderung, welche zu einem Erfolgskriterium 4. Stufe gehört, würde mit einer eigenen Überschrift das Limit von 6 Stufen sprengen)!

Im Falle einer Überschreitung der verfügbaren Ebenen wandelt Markdown das Element einfach in einen Paragraphen um: es entsteht technisch also kein Problem, semantisch aber schon.

Pandoc

A4AA 2.0 verwendet Pandoc als Markdown-Parser. Dieses unterstützt neben der Grundsyntax viele weitere Auszeichnungsmöglichkeiten in Markdown, etwa inline-Code, Inhaltsverzeichnis, Tabellen, Bibligraphien, Referenzen, Fussnoten, etc. Mehr Infos hier: Pandoc User’s Guide.

Export nach Docx, HTML, Markdown…

Pandoc ist ein “universeller Dokument-Konverter”, d.h. es kann verschiedene Dokumentformate umwandeln, wobei intern Markdown als Grundformat verwendet wird. Pandoc wird von A4AA 2.0 verwendet, um Berichte nach Word Docx, Epub, etc. zu exportieren.

Pandoc online ausprobieren

Die Seite pandoc.org/try/ lädt ein zum fröhlichen Experimentieren mit Markdown und dem Konvertieren zwischen verschiedenen Eingabe- und Ausgabeformaten.

Wichtig: A4AA 2.0 verwendet momentan Pandoc Version 1.16 (diese ist auf dem Server fix installiert); es sind also möglicherweise gewisse Funktionen, welche später eingeführt worden sind, nicht verfügbar.

Allgemeine Infos hier: Pandoc’s markdown