Seitengestaltung mit Markdown

Im Folgenden wird die Einbindung von Seiten mittels der Auszeichnungssprache Markdown erklärt.

Struktur

Seiten die mit Markdown arbeiten nutzen das Markdown-Template index.md statt des HTML-Templates index.src.html. Die CSS-Styles werden unter /css/spec.css definiert.

Syntax

Die vollständige Syntax von Markdown ist unter http://markdown.de/ dokumentiert. Im Folgenden werden die wichtigsten Funktionalitäten beschrieben.

Absätze und Umbrüche

Absätze werden durch Leerzeilen voneinander getrennt.

1. Absatz 2. Absatz

Einen Umbruch erzwingt man durch zwei Leerzeichen vor dem Umbruch.

Text vor dem Umbruch Text nach dem Umbruch

Abschnitte und Seitentitel

Abschnitte der gewünschten Ebene und Seitentitel werden mit # zu Beginn einer Zeile definiert. Im Gegensatz zu herkömmlichen Überschriften, zu denen der Seitentitel gehört, dienen Abschnitte auch zur hierarchischen Strukturierung der Seiten und werden entsprechend in der Inhalts-Navigation angezeigt.

# Dies ist der Seitentitel ## Dies ist ein Abschnitt auf erster Ebene ### Dies ist ein Abschnitt auf zweiter Ebene #### Dies ist ein Abschnitt auf dritter Ebene

Bilder

Bilder können mit Markdown eingebunden werden.

![Alternativer Text falls Bild nicht geladen werden kann](/Pfad/zum/Bild.jpg)

Code-Blöcke

Code-Blöcke erlauben die Darstellung von Quellcode ohne dass dieser gerendert wird. So kann beispielsweise HTML- und Markdown-Syntax erkärt werden und wird auch auf dieser Anleitungsseite verwendet.

``` code  
Hier steht der Code  
``` 

HTML

HTML kann in Markdown frei verwendet werden. Es ist nicht nötig, HTML zu markieren um es vom Rest abzugrenzen.

HTML-Beispiele

Besonders wichtig für den Styleguide ist die Einbindung von HTML-Beispielen, deren Quellcode bei Bedarf angezeigt werden kann.

``` example   
<a class="btn btn-primary" href="#777">Example button</a>``` 

Markdown erlaubt das Erstellen von Hyperlinks mit dem gewünschten Text.

[SourceJS](https://sourcejs.com/)

SourceJS

Listen und Aufzählungen

Ungeordnete Listen können mit einem - zu Beginn der Zeile definiert werden.

- erstes Element - zweites Element
  • erstes Element
  • zweites Element

Aufzählungen werden durch Zahlen zu Beginn der Zeile definiert.

1. Element 2. Element
  1. Element
  2. Element

Quellenverweise

Die Markdown-Syntax wurde für den NetzDatenStrom Styleguide mit der Auszeichnung von Quellenverweisen erweitert. Bei der Einbindung von Quellen ist zwischen Quellen die einmalig zitiert werden und Mehrfachzitierungen zu unterscheiden.

a) Quelle wird nur einmal auf gesamter Specseite referenziert:


cite{ Quellenangaben } 

b) Bei mehrfacher Zitierung im Text werden Quellen über einen Gruppennamen referenziert.
Dieser muss an der ersten Verweisstelle gemeinsam mit den Quellenangaben definiert werden:


cite{ (name=Gruppenname) Quellenangaben }

An späteren Textstellen wird die Quelle nur über den Gruppennamen referenziert:


cite{ (name=Gruppenname) }

Einschränkungen

Beim Einfügen von Quellenverweisen müssen folgende Einschränkungen beachtet werden:

  • Geschweifte Klammern dürfen in den Quellenangaben nicht verwendet werden.
  • Markdown-Referenzierung wird nicht über Zeilenumbrüche hinweg erkannt, sondern nur korrekt geparsed falls sie in einer Zeile steht.
  • Falls eine Quelle mit gleichem Gruppennamen und verschiedenen Quellenangaben definiert ist, werden zur Wahrung der Konsistenz nur die Quellenangaben der ersten Referenzierung verwendet.

Sonderzeichen escapen

Um einzelne Sonderzeichen der Markdown-Syntax zu escapen wird Backslash (\) eingesetzt.

\* Sternchen \*

* Sternchen *

Tabellen

Für Tabellen werden senkrechte Striche (|) zur Abgrenzung der Spalten und Bindestriche (-) zur Abgrenzung des Tabellenkopfes vom Tabellenkörper eingesetzt.

Spalte 1 | Spalte 2 | Spalte 3 -------- | -------- | -------- Inhalt | Inhalt | Inhalt Inhalt | Inhalt | Inhalt
Spalte 1 Spalte 2 Spalte 3
Inhalt Inhalt Inhalt
Inhalt Inhalt Inhalt

Text-Auszeichnung

Text wird durch * hervorgehoben.

*kursiv* **fett**

kursiv
fett

Trennlinien

Trennlinien können durch drei aufeinanderfolgende Unterstriche (_) eingefügt werden.

Text vor Trennlinie. ___ Text nach Trennlinie.

Text vor Trennlinie


Text nach Trennlinie