9.4 KiB
Table of Contents
Markdown
Einen Text in Markdown schreibt man mit jedem einfachen Editor.
Caution
In Markdown schreibt man nur den strukturierten Text. Man kümmert sich NICHT um das Layout.
In diesem Bereich versuchen wir die wichtigsten Befehle zu beschreiben. Die folgenden Elemente kennt Markdown.
Text
Texte bestehen in der Regel auf Sätzen und Absätzen.
Sätze
Jeder Satz wird in eine Zeile geschrieben.
Absätze
Nach jedem Absatz wir eine Leerzeile eingefügt. Sie trennt die Absätze von einander. Auch nach jeder Überschrift sollte man eine Leerzeile einfürgen, bevor man weiteren Text hinzufügt.
Dies ist der 1. Absatz.
Jeder Satz steht in einer eigenen Zeile.
Den Absatz beendet man mit einer Leerzeile.
Diese sollte man auch vor und nach Überschriften machen.
ergibt
Dies ist der 1. Absatz. Jeder Satz steht in einer eigenen Zeile.
Den Absatz beendet man mit einer Leerzeile. Diese sollte man auch vor und nach Überschriften machen.
Zeilenumbruch innerhalb eines Absatzes
Man sollte eigentlich nur selten einen Zeilenumbruch innerhalb eines Absatzes machen. Es ist jedoch in Markdown auch möglich. Dazu hängt man zwei Leerzeichen an das Ende der Zeile, nach der umgebrochen werden soll.
Sinnvoll kann dies bei Signaturen sein.
Werner Muster
Mustergasse 12
99999 Musterstadt
ergibt
Werner Muster
Mustergasse 12
99999 Musterstadt
Überschriften
Überschriften strukturieren ein Dokument. Sie bieten zusätzlich den Vorteil, dass sie automatisch mit einer ID versehen werden, sodass sie direkt angesprungen werden können.
Tip
Visual Studio Code listed beim Editieren eines Links alle internen IDs auf, wenn man ein
#angibt.
Überschriften beginnen immer mit einem #.
Die Anzahl der # ergibt die Stufe.
# wird in <h1> konvertiert.
## wird in <h2> konvertiert usw.
Die Stufe wir mit einem Leerzeichen vom Text getrennt.
Vor und nach jeder Überschrift sollte eine Leerzeile sein. Dies erhöht auch die Lesbarkeit im Textmodus.
H1-Überschriften sollten wie Buchtitel verwendet werden. Da unsere Dokumente eher ein Kapitel darstellen, sollten wir mit H2-Überschriften beginnen.
Der letzte Absatz.
#### die Überschrift
Der 1. Absatz nach der Überschrift.
...
ergibt
Der letzte Absatz.
Die Überschrift
Der 1. Absatz nach der Überschrift. ...
Bilder
Bilder können über einen speziellen Link als Inlinedokument eingebunden werden.
Man sollte vermeiden, für Bilder die HTML-Tags direkt zu verwenden. Bei HTML-Tags kann man zwar die Größe anpassen, aber dies sollte man vermeiden, da man nie weiß, auf welchem Gerät und in welcher Größe das Bild angezeigt wird.
Es werden die Formate .png, .svg und .jpg unterstützt.
ergibt
Links
Da Markdowndokumente meistens als HTML Dateien übersetzt und in einem Browser angezeigt werden, sind Links das Salz in der Suppe. Jeder Link hilft dem Anwender schnell an detaillierte Informationen zu gelangen.
Einen Link kann man sehr leicht hinzufügen. Das Wort bzw. der Begriff, der angeklickt werden kann, wird in eckigen Klammern geschrieben. Danach schreibt man in runden Klammern den Pfad zum Dokument. In GitHub und in Visual Studio Code kann man den Pfad zu einem anderen Markdowndokument angeben.
Will man im Zieldokument an eine bestimmte Stelle springen, so kann man die ID mit einem vorangestellten # an den Pfad anhängen.
So gelangt man an den [Kopf](#markdown) dieses Dokumentes.
So gelangt man zum Abschnitt [Kopfdaten](app.md#kopfdaten) in der Beschreibung zur Anwendungsdokumentation.
ergibt
So gelangt am an den Kopf. So gelangt man zum Abschnitt Kopfdaten in der Beschreibung zur Anwendungsdokumentation.
Inline Formatierungen
Manchmal möchte man auch innerhalb eines Satzes ein Wort hervorheben. Dafür stehen 2 Möglichkeiten zur Verfügung.
Fettschrift
Wenn man Worte fett dargestellt haben möchte, kann man diese in ** klammern.
Grundsätzlich erlaubt Markdown auch __, davon sollte man aber wegen der einheitlicheren Lesbarkeit absehen.
In Überschriften sollte man möglichst auf die Fettschrift verzichten.
Dieses **Wort** ist fett geschrieben.
ergibt
Dieses Wort ist fett geschrieben.
Kursivschrift
Wenn man Worte kursiv dargestellt haben möchte, kann man diese in * klammern.
Grundsätzlich erlaubt Markdown auch _, davon sollte man aber wegen der einheitlicheren Lesbarkeit absehen.
In Überschriften sollte man möglichst auf die Fettschrift verzichten.
*Dieser Satz ist kursiv geschrieben.*
ergibt
Dieser Satz ist kursiv geschrieben.
Code
Dateinamen, Befehle oder Wörter, die aus dem Quellcode übernommen wurden, können in ` geklammert werden.
Mit `git pull` holt man den aktuellen Code vom Server.
ergibt
Mit
git pullholt man den aktuellen Code vom Server.
Zeilenumbruch
Manchmal möchte man einen Zeilenumbruch innerhalb eines Absatzes erzwingen. Dies erreicht man, indem man 2 Leerzeichen ans Zeilenende anhängt.
Dies ist der 1. Absatz.
Mit einem Zeilenumbruch.
Dies ist der 2. Absatz.
ohne einem Zeilenumbruch.
ergibt
Dies ist der 1. Absatz.
Mit einem Zeilenumbruch.Dies ist der 2. Absatz. ohne einem Zeilenumbruch.
Listen
Listen werden verwendet, wenn man eine Aufzählung von Dingen hat. Sie können auch verschachtelt genutzt werden.
Nummerierte Listen
Nummerierte Listen sollten immer mit 1. und einem Leerzeichen beginnen.
Danach folgt der 1 Satz.
Weitere Sätze können in der nächsten Zeile geschrieben werden.
Zwischen den einzelnen Listeneinträgen sollte keine Leerzeile stehen.
1. Dies ist der 1. Eintrag.
Hier folgt der 2. Satz.
1. Dies ist der 2. Eintrag.
1. Dies ist der 3. Eintrag.
6. Falsche Nummern werden korrigiert.
ergibt
- Dies ist der 1. Eintrag. Hier folgt der 2. Satz.
- Dies ist der 2. Eintrag.
- Dies ist der 3. Eintrag.
- Falsche Nummern werden korrigiert.
Aufzählungslisten
Aufzählungslisten sollten immer mit - oder * und einem Leerzeichen beginnen.
Danach folgt der 1 Satz.
Weitere Sätze können in der nächsten Zeile geschrieben werden.
Zwischen den einzelnen Listeneinträgen darf keine Leerzeile stehen.
- Dies ist der 1. Eintrag.
Hier folgt der 2. Satz.
- Dies ist der 2. Eintrag.
* Dies ist der 1. Eintrag einer neuen Liste.
Der Wechsel des Aufzählungszeichens führt zu einer neuen Liste.
ergibt
- Dies ist der 1. Eintrag. Hier folgt der 2. Satz.
- Dies ist der 2. Eintrag.
- Dies ist der 1. Eintrag einer neuen Liste. Der Wechsel des Aufzählungszeichens führt zu einer neuen Liste.
Verschachtelte Listen
Man kann auch innerhalb einer Liste eine verschachtelte Liste anlegen. Die Art der Liste kann auch wechseln.
Um eine verschachtelte Liste anzulegen, rückt man den neuen Eintrag so ein, dass das Listenzeichen (1 oder *) mit dem Text der oberen Liste beginnt.
- Dies ist der 1. Eintrag.
Hier folgt der 2. Satz.
1. Dies ist der 1. Eintrag der verschachtelten Liste.
1. Dies ist der nächste Eintrag der verschachtelten Liste.
- Hier geht die äußere Liste weiter.
ergibt
- Dies ist der 1. Eintrag.
Hier folgt der 2. Satz.
- Dies ist der 1. Eintrag der verschachtelten Liste.
- Dies ist der nächste Eintrag der verschachtelten Liste.
- Hier geht die äußere Liste weiter.
Tabellen
In Markdown können einfache Tabellen verwendet werden. In Hinblick auf die Darstellung auf unterschiedlichen Geräten, sollte man keine komplizierten Tabellen anlegen.
Jede Tabelle hat eine Überschriftszeile und mehrere Datenzeilen.
Für jede Spalte muss ein | Zeichen zischen den Tabelleneinträge geschrieben werden.
Dies muss jeweils mit mindestens einem Leerzeichen vom Text getrennt werden.
Damit der Text als Tabelle erkannt wird, muss die 2. Zeile die Spaltendefinition enthalten.
- Sie muss mit einem
|beginnen und enden. - Jede Spalte muss mit einem
|von der nächsten Spalte getrennt werden. - Für jede Spalte müssen mindestens 3
-eingetragen werden. - Die Spaltenausrichtung kann mit
:- am Anfang oder ohne (linksbündig),
- an beiden Seiten (zentriert) oder
- am Ende (rechtsbündig) festgelegt werden.
Pos. | Beschreibung | Preis
|:---:|---|---:|
1 | Allgemeines Blabla |
1.1 | Begrüßung | 2,00 EUR
1.2 | Vorstellung der Teilnehmer | 1.234,50 EUR
2 | Diskussion | 23,87 EUR
3 <td colspan=2> 2,76 EUR |
ergibt
Pos. Beschreibung Preis 1 Allgemeines Blabla 1.1 Begrüßung 2,00 EUR 1.2 Vorstellung der Teilnehmer 1.234,50 EUR 2 Diskussion 23,87 EUR 3 2,76 EUR
Hinweis-Boxen
Man kann wichtige Informationen als Hinweisbox darstellen lassen.
>[!NOTE]
>Dies ist eine Notiz.
ergibt
Note
Dies ist eine Notiz.
>[!TIP]
>Dies ist ein Hinweis.
ergibt
Tip
Dies ist ein Hinweis.
>[!IMPORTANT]
>Dies ist ein wichtiger Hinweis.
ergibt
Important
Dies ist ein wichtiger Hinweis.
>[!WARNING]
>Dies ist eine Warnung.
ergibt
Warning
Dies ist eine Warnung.
>[!CAUTION]
>Dies ist eine eindringliche Warning.
ergibt
Caution
Dies ist eine eindringliche Warning.