Markdown Einführung

{%hackmd DOSUYLKKT0ulj8VzbGqgxA %} ![Markdown Tapete - 1536x1024](https://hackmd.io/_uploads/ry1AQcq6lg.jpg) > *Eine kurze Einführung in das Thema Markdown, das Werkzeug zur Dokumentation aller Art in modernen Umgebungen.* > Aufwand: ca. 10-20 Minuten # 1. Markdown Einführung --- [TOC] --- ## 1.1 Wofür braucht man Markdown? ### a) Definition Genau wie HTML oder LaTeX ist Markdown eine Auszeichnungssprache. Im Gegensatz zu diesen soll Markdown jedoch möglichst leicht von Menschen zu lesen und zu schreiben sein. Daher der Name „Markdown“ anstelle von „Markup“. ### b) Vergleich mit HTML In HTML schreibt man für eine Überschrift erster Ebene (h1) und einen Absatz (p) mit einem fett gedruckten Wort folgendes: ```html  <h1>Überschrift</h1>    <p>Dieses <b>Wort</b> ist fett.</p> ``` :::danger <h1>Überschrift</h1> <p>Dieses <b>Wort</b> ist fett.</p> ::: ### c) Vergleich mit LaTeX In LaTeX verwendet man im Fließtext-Modus das Element `\textbf`: ```latex % LaTeX Code \section{Überschrift} % \section for a section caption % \textbf for text in bold face Dieses \textbf{Wort} ist fett. ``` ### d) Markdown-Syntax Beides ist einigermaßen lesbar, aber schwieriger zu schreiben, besonders bei längeren Texten. Markdown vereinfacht dies, indem fettgedruckte Passagen einfach mit Sternchen markiert werden: ```markdown # Überschrift Dieses **Wort** ist fett. ``` :::info Wenn Sie Markdown direkt testen möchten und dies nicht in HedgeDoc oder auf http://hackmd.io tun wollen, bietet sich https://stackedit.io an. Allerdings unterstützt der Online-Editor nicht alle Markdown-Funktionen. ::: ## 1.2 Markdown – die einfache Auszeichnungssprache ### a) Lesbarkeit Wenn wir Texte lesen, sei es im Internet, in einer Zeitschrift oder einem Buch, erwarten wir ein bestimmtes Format. Wichtige Wörter sind fett gedruckt, Überschriften heben sich klar vom Text ab, und Listen machen Inhalte anschaulicher. Solche Formatierungen nehmen wir als selbstverständlich wahr. ### b) Formatierung in Textverarbeitungsprogrammen Beim Verfassen eines Textes am PC ist dies meist unkompliziert: Schriftgröße anpassen, Aufzählungszeichen setzen oder Wörter fett formatieren. Jedes Textverarbeitungsprogramm bietet zahlreiche Möglichkeiten, Texte ansprechend zu gestalten. ### c) Unterschied zu Word & Co. Das ist jedoch nicht selbstverständlich. In solchen Programmen markieren Sie den Text, und die Software rendert ihn entsprechend. Den eigentlichen Quelltext mit den Auszeichnungselementen sieht man bei Word & Co. nicht – und könnte damit auch wenig anfangen, da dieser Code für Menschen kaum lesbar ist. ### d) Vorteile von Markdown Sprachen wie HTML oder LaTeX lassen sich zwar mit jedem Texteditor schreiben, sind aber schwer zu entziffern. Markdown will genau das ändern: Es kombiniert die Vorteile beider Welten und ist sowohl für Maschinen als auch für Menschen leicht verständlich. Markdown verwendet intuitive Elemente, um Texte zu formatieren, sodass auch der ausgezeichnete Text gut lesbar bleibt. ## 1.3 HTML-Embedding ### a) Einbettung von HTML In Markdown kann HTML eingebettet werden. Da Markdown-Anweisungen letztlich in HTML umgewandelt werden, ist dies im Endergebnis (z. B. PDF oder HTML-Seite) kaum erkennbar. # 2. Gliederung / Überschriften ## 2.1 Möglichkeiten zur Erstellung ### a) Klassischer ReadMe-Stil Überschriften können auf zwei Arten erstellt werden: klassisch im ReadMe-Stil oder systematisch mit dem `#`-Zeichen. ### b) Übersichtstabelle <table class="table table-bordered"> <thead class="thead-light"> <tr> <th>Markdown</th> <th>HTML</th> <th>Gerenderte Ausgabe</th> </tr> </thead> <tbody> <tr> <td><code class="highlighter-rouge"># Heading level 1</code></td> <td><code class="highlighter-rouge"><h1>Heading level 1</h1></code></td> <td><h1 class="no-anchor" data-toc-skip="" id="heading-level-1">Heading level 1</h1></td> </tr> <tr> <td><code class="highlighter-rouge">## Heading level 2</code></td> <td><code class="highlighter-rouge"><h2>Heading level 2</h2></code></td> <td><h2 class="no-anchor" data-toc-skip="" id="heading-level-2">Heading level 2</h2></td> </tr> <tr> <td><code class="highlighter-rouge">### Heading level 3</code></td> <td><code class="highlighter-rouge"><h3>Heading level 3</h3></code></td> <td><h3 class="no-anchor" data-toc-skip="" id="heading-level-3">Heading level 3</h3></td> </tr> <tr> <td><code class="highlighter-rouge">#### Heading level 4</code></td> <td><code class="highlighter-rouge"><h4>Heading level 4</h4></code></td> <td><h4 class="no-anchor" id="heading-level-4">Heading level 4</h4></td> </tr> <tr> <td><code class="highlighter-rouge">##### Heading level 5</code></td> <td><code class="highlighter-rouge"><h5>Heading level 5</h5></code></td> <td><h5 class="no-anchor" id="heading-level-5">Heading level 5</h5></td> </tr> <tr> <td><code class="highlighter-rouge">###### Heading level 6</code></td> <td><code class="highlighter-rouge"><h6>Heading level 6</h6></code></td> <td><h6 class="no-anchor">Heading level 6</h6></td> </tr> </tbody> </table> # 3. Formatierungselemente ## 3.1 Absätze ### a) Erstellung Ein neuer Absatz wird durch zwei Zeilenumbrüche (zweimal die Eingabetaste) eingeleitet. Zwischen den Textzeilen muss also eine Leerzeile stehen. ### b) Beispiel ```markdown Lorem ipsum dolor sit amet, *consetetur* sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, **consetetur** sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. ``` ### c) Gerenderte Ausgabe ```html <div> <p>Lorem ipsum dolor sit amet, <em>consetetur</em> sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum.</p> <p>Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.<br/> Lorem ipsum dolor sit amet, <strong>consetetur</strong> sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.</p> </div> ``` :::danger Lorem ipsum dolor sit amet, *consetetur* sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, **consetetur** sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. ::: ## 3.2 Blockzitate ### a) Syntax ```markdown > # Foo > bar > baz ``` ### b) HTML-Ausgabe Für Blockzitate (bekannt aus E-Mails) wird das `>`-Zeichen vorangestellt. ```html <blockquote> <h1>Foo</h1> <p>bar baz</p> </blockquote> ``` ### c) Beispiel :::danger > # Foo > bar > baz ::: ### d) Geschachtelte Blockzitate Blockzitate können auch geschachtelt werden. ## 3.3 Fett und Kursiv ### a) Syntax ```markdown **Fett** und *Kursiv* ``` ### b) HTML-Ausgabe ```html <b>Fett</b> und <i>Kursiv</i> ``` ### c) Beispiel :::danger **Fett** und *Kursiv* ::: ## 3.4 Durchstreichen ### a) Syntax ```markdown ~~Dieser Text ist durchgestrichen.~~ Dieser aber nicht. ``` ### b) HTML-Ausgabe ```html <s>Dieser Text ist durchgestrichen.</s> Dieser aber nicht. ``` ### c) Beispiel :::danger ~~Dieser Text ist durchgestrichen.~~ Dieser aber nicht. ::: ## 3.5 Markieren ### a) Syntax ```markdown ==Dieser Text ist markiert.== Dieser aber nicht. ``` ### b) HTML-Ausgabe ```html <mark>Dieser Text ist markiert.</mark> Dieser aber nicht. ``` ### c) Beispiel :::danger ==Dieser Text ist markiert.== Dieser aber nicht. ::: ## 3.6 Unterstreichen ### a) Einschränkung :::warning **Achtung**: In Markdown kann Text nicht unterstrichen werden. In HTML ist dies mit dem `<u>`-Tag möglich, wird jedoch nicht empfohlen, da unterstrichener Text mit Hyperlinks verwechselt werden könnte. ::: ### b) Beispiel ```markdown Ansonsten ist <u>dieser Text unterstrichen</u>. ``` :::danger Ansonsten ist <u>dieser Text unterstrichen</u>. ::: ## 3.7 Hoch- und Tiefschrift ### a) Syntax ```markdown H₂O -> H~2~O -> C^14^ ``` ### b) Beispiel :::danger H₂O -> H~2~O -> C^14^ ::: ## 3.8 Links und URLs ### a) URLs Alle URLs, die als solche erkannt werden, werden automatisch als Links gerendert. Relative URLs wie `/sub` werden nicht automatisch verlinkt. ```markdown Direkte URL: https://app.diagrams.net/ ``` :::danger Direkte URL: https://app.diagrams.net/ ::: ### b) Links Mit eckigen Klammern vor der URL in runden Klammern kann der Linktext definiert werden. ```markdown Link: [draw.io](https://app.diagrams.net/) ``` :::danger Link: [draw.io](https://app.diagrams.net/) ::: ### c) Erweiterte Syntax Eine komplexere Syntax mit Doppelpunkt ermöglicht zusätzliche Attribute wie `target` (hier von HedgeDoc nicht vollständig unterstützt). ```markdown [draw.io]: https://apps.diagrams.net/ "Web Zeichenprogramm" [draw.io] ``` :::danger [draw.io]: https://apps.diagrams.net/ "Web Zeichenprogramm" [draw.io] ::: ## 3.9 Auflistungen ### a) Syntax Ungeordnete Listen sollten ohne Leerzeilen geschrieben werden. Als Listenzeichen können `-`, `*` oder `+` verwendet werden, wobei dies das gerenderte Symbol nicht beeinflusst. ```markdown * Punkt 1 * Punkt 2 - Punkt 2.1 - Punkt 2.2 * Punkt 3 ``` ### b) Beispiel :::danger * Punkt 1 * Punkt 2 - Punkt 2.1 - Punkt 2.2 * Punkt 3 ::: ## 3.10 Aufzählungen ### a) Syntax Geordnete Listen müssen ohne Leerzeilen geschrieben werden. Die Nummerierung wird automatisch fortlaufend generiert, unabhängig von der im Markdown angegebenen Nummer. ```markdown 1. Punkt 1 2. Punkt 2 1. Punkt 2.1 2. Punkt 2.2 3. Punkt 2.3 3. Punkt 3 ``` ### b) Beispiel :::danger 1. Punkt 1 2. Punkt 2 1. Punkt 2.1 2. Punkt 2.2 3. Punkt 2.3 3. Punkt 3 ::: ### c) Fehlerhafte Nummerierung Auch eine fehlerhafte Nummerierung wird korrekt durchgezählt: ```markdown 1. Punkt 1 1. Punkt 2 1. Punkt 2.1 2. Punkt 2.2 3. Punkt 2.3 1. Punkt 3 ``` :::danger 1. Punkt 1 1. Punkt 2 1. Punkt 2.1 2. Punkt 2.2 3. Punkt 2.3 1. Punkt 3 ::: ### d) Getrennte Listen Trennt eine Leerzeile oder ein anderes Element die Liste, wird die Nummerierung neu gestartet. ```markdown 1. Punkt 1 weiter 3. Punkt 2 1. Punkt 2.1 2. Punkt 2.2 3. Punkt 2.3 3. Punkt 3 ``` :::danger 1. Punkt 1 weiter 3. Punkt 2 1. Punkt 2.1 2. Punkt 2.2 3. Punkt 2.3 3. Punkt 3 ::: ## 3.11 Check-Listen ### a) Syntax ```markdown - [ ] Einkaufen - [X] Müll runterbringen - [ ] Aufräumen - [ ] Wohnzimmer - [ ] Bad ``` ### b) Beispiel :::danger - [ ] Einkaufen - [X] Müll runterbringen - [ ] Aufräumen - [ ] Wohnzimmer - [ ] Bad ::: :::success Klicken Sie auf die Checkboxen, um sie auszuprobieren! -> mit Schreibrechten im Dokument können Sie diese verändern ! ::: ## 3.12 Definitionslisten ### a) Syntax ```markdown cpan.org : Comprehensive Perl Archive Network – eine Online-Bibliothek für Perl-Packages mit Suchfunktion und Tutorials zu allen Paketen. perl.org : Offizielle Webseite zu Perl ``` ### b) Beispiel :::danger cpan.org : Comprehensive Perl Archive Network – eine Online-Bibliothek für Perl-Packages mit Suchfunktion und Tutorials zu allen Paketen. perl.org : Offizielle Webseite zu Perl ::: ## 3.13 Tabellen ### a) Konzept Tabellen in Markdown sind so gestaltet, dass sie auch in einer ReadMe-Datei lesbar sind. Mit `-` und `|` werden Tabellen im Text gezeichnet, die in HTML-Tabellen umgewandelt werden. ### b) Kleine einfache Tabelle Die Spaltenbreite wird automatisch ermittelt. ```markdown | Column 1 | Column 2 | Column 3 | | -------- | -------- | -------- | | Text | Text | Text | | Info | Info | Info | ``` :::danger | Column 1 | Column 2 | Column 3 | | -------- | -------- | -------- | | Text | Text | Text | | Info | Info | Info | ::: ### c) Beispiel ```markdown :::success ## Stunden und Pausen: - [ ] Einverstanden? | Von | Bis | Was | | ------ | ------ | ------------ | | 9:00 | 10:15 | Block 1 | | 10:15 | 10:30 | Frühstück | | 10:30 | 12:30 | Block 2 | | 12:30 | 13:30 | Mittagspause | | 13:30 | ~14:50 | Block 3 | | ~14:50 | ~15:05 | Kaffeepause | | ~15:05 | 16:00 | Block 4 | ::: ``` :::danger :::success ## Stunden und Pausen: - [ ] Einverstanden? | Von | Bis | Was | | ------ | ------ | ------------ | | 9:00 | 10:15 | Block 1 | | 10:15 | 10:30 | Frühstück | | 10:30 | 12:30 | Block 2 | | 12:30 | 13:30 | Mittagspause | | 13:30 | ~14:50 | Block 3 | | ~14:50 | ~15:05 | Kaffeepause | | ~15:05 | 16:00 | Block 4 | ::: ::: ### d) CSV ```markdown '''csv Username;Identifier;One-time password;Recovery code;First name;Last name;Department;Location booker12;9012;12se74;rb9012;Rachel;Booker;Sales;Manchester grey07;2070;04ap67;lg2070;Laura;Grey;Depot;London johnson81;4081;30no86;cj4081;Craig;Johnson;Depot;London jenkins46;9346;14ju73;mj9346;Mary;Jenkins;Engineering;Manchester smith79;5079;09ja61;js5079;Jamie;Smith;Engineering;Manchester ''' ``` --- ```csv Username;Identifier;One-time password;Recovery code;First name;Last name;Department;Location booker12;9012;12se74;rb9012;Rachel;Booker;Sales;Manchester grey07;2070;04ap67;lg2070;Laura;Grey;Depot;London johnson81;4081;30no86;cj4081;Craig;Johnson;Depot;London jenkins46;9346;14ju73;mj9346;Mary;Jenkins;Engineering;Manchester smith79;5079;09ja61;js5079;Jamie;Smith;Engineering;Manchester ``` ### e) CSV Tables Daten im CSV-Format können direkt in Tabellen umgewandelt werden. ```markdown Als Tabelle: '''csvpreview Username;Identifier;One-time password;Recovery code;First name;Last name;Department;Location booker12;9012;12se74;rb9012;Rachel;Booker;Sales;Manchester grey07;2070;04ap67;lg2070;Laura;Grey;Depot;London johnson81;4081;30no86;cj4081;Craig;Johnson;Depot;London jenkins46;9346;14ju73;mj9346;Mary;Jenkins;Engineering;Manchester smith79;5079;09ja61;js5079;Jamie;Smith;Engineering;Manchester ''' ``` :::danger <font size="-2">Als Tabelle: ```csvpreview Username;Identifier;One-time password;Recovery code;First name;Last name;Department;Location booker12;9012;12se74;rb9012;Rachel;Booker;Sales;Manchester grey07;2070;04ap67;lg2070;Laura;Grey;Depot;London johnson81;4081;30no86;cj4081;Craig;Johnson;Depot;London jenkins46;9346;14ju73;mj9346;Mary;Jenkins;Engineering;Manchester smith79;5079;09ja61;js5079;Jamie;Smith;Engineering;Manchester ``` </font> ::: ## 3.14 Blocks (Bootstrap Alerts) ### a) Konzept Box-Blöcke sind eine ansprechende Möglichkeit, Texte hervorzuheben. ### b) Beispiel ```markdown :::success **Notiz**: Bitte hier weiter machen... ::: :::info **Info**: Bitte hier weiter machen... ::: :::warning **Warnung**: Bitte hier weiter machen... ::: :::danger **Fehler**: Bitte hier weiter machen... ::: ``` :::danger :::success **Notiz**: Bitte hier weiter machen... ::: :::danger :::info **Info**: Bitte hier weiter machen... ::: :::danger :::warning **Warnung**: Bitte hier weiter machen... ::: :::danger :::danger **Fehler**: Bitte hier weiter machen... ::: ## 3.15 Code / Befehl ### a) Inline-Code Ein Code oder Befehl wie `cmd.exe` kann inline erwähnt werden. ```markdown In einem Text kann ein Code / Befehl wie `cmd.exe` erwähnt werden... ``` ### b) Beispiel :::danger In einem Text kann ein Code / Befehl wie `cmd.exe` erwähnt werden... ::: ## 3.16 Quellcode (Untypisiert) ### a) Syntax Ein Quellcodeblock beginnt und endet mit mindestens drei Backticks (```). :::warning Im Markdown-Code unten sind jeweils drei Backticks dargestellt! ::: ### b) Einfacher Perl-Code ```markdown ```text #!/usr/bin/perl -w # fahr2cel.pl print "Fahrenheit: "; $f = <STDIN>; my $c = 5/9*($f-32); print "Celsius: ", $c ,"\n"; ``' ``` --- :::danger ``` #!/usr/bin/perl -w # fahr2cel.pl print "Fahrenheit: "; $f = <STDIN>; my $c = 5/9*($f-32); print "Celsius: ", $c ,"\n"; ``` ::: ## 3.17 Quellcode (Typisiert + Nummeriert) ### a) Syntax Für die Zeilennummerierung fügen Sie hinter der Syntax ein `=` ein. ```markdown ```perl= #!/usr/bin/perl -w # fahr2cel.pl print "Fahrenheit: "; $f = <STDIN>; my $c = 5/9*($f-32); print "Celsius: ", $c ,"\n"; ``' ``` ### b) Beispiel :::danger ```perl= #!/usr/bin/perl -w # fahr2cel.pl print "Fahrenheit: "; $f = <STDIN>; my $c = 5/9*($f-32); print "Celsius: ", $c ,"\n"; ``` ::: ## 3.18 E-Mail-Adressen ### a) Direkte E-Mail-URL ```markdown Direkte E-Mail-URL: mailto:user@home.de ``` ### b) E-Mail-Link ```markdown E-Mail-Link: [email@home](mailto:user@home.de) ``` ### c) Beispiel :::danger Direkte E-Mail-URL: mailto:user@home.de E-Mail-Link: [email@home](mailto:user@home.de) ::: ## 3.19 Bilder ### a) Bild als SVG ```markdown ![Markdown](https://upload.wikimedia.org/wikipedia/commons/4/48/Markdown-mark.svg) ``` :::danger ![Markdown](https://upload.wikimedia.org/wikipedia/commons/4/48/Markdown-mark.svg) ::: ### b) Bild als PNG Ein Bild als PNG, auf 350 Pixel Breite beschnitten: ```markdown ![Markdown](https://upload.wikimedia.org/wikipedia/commons/thumb/4/48/Markdown-mark.svg/640px-Markdown-mark.svg.png =350x) ``` :::danger ![Markdown](https://upload.wikimedia.org/wikipedia/commons/thumb/4/48/Markdown-mark.svg/640px-Markdown-mark.svg.png =350x) ::: ## 3.20 LaTeX-Formeln ### a) Beispiel ```markdown The Gamma function satisfying $\Gamma(n) = (n-1)!\quad\forall n\in\mathbb N$ is via the Euler integral $$ \Gamma(z) = \int_0^\infty t^{z-1}e^{-t}dt\,. $$ ``` :::danger The Gamma function satisfying $\Gamma(n) = (n-1)!\quad\forall n\in\mathbb N$ is via the Euler integral $$ \Gamma(z) = \int_0^\infty t^{z-1}e^{-t}dt\,. $$ ::: # 4. Beispiele für weitere Möglichkeiten ## 4.1 Textbasierte Diagramme ### a) PlantUML -> Sequenzdiagramm ```plantuml @startuml participant MainForm activate MainForm MainForm -> Button: click << btnSquare >> Button -> Square: new << createRequest >> activate Square #FFBBBB activate List #DarkSalmon Square -> List: append Square <-- List: << return >> Button <-- Square: << return >> deactivate Square MainForm <-- Button: << return >> MainForm -> List: iterate List -> List: Draw() MainForm <-- List: << return >> @enduml ``` --- ### Zusammenfassung - **Markup**: Markdown ist absichtlich kein Markup, sondern vereinfacht das schreiben von narativen Dokumenten enorm. - **Standard**: Es gibt mehere Dialekte aber keinen einheitlichen Standard - **Markdown**: lässt sich sehr einfach in LaTeX oder nach Word überführen - mehr als 120 Formate sind heute Unterstützt... - **Technisch**: Korrektur von LaTeX-Syntax (H₂O), CSV-Formatierung, und Markdown-Syntaxfehler - **Stil**: Klarere Syntax-Formulierungen und Verbesserung der Lesbarkeit