umr
guf
fra-uas
hda
hsgm
hsrm
tuda
thm
jlu
uks
hfd
hmwk

Einführung in Markdown

…und Beispiele für dessen Anwendungsbereiche

Referent: Andre M. Pietsch (JLU Gießen)
E-Mail: Andre.M.Pietsch@bibsys.uni-giessen.de

Heutige Ziele

…oder Fragen, auf die Sie nach dem heutigen Vortrag Antworten haben sollten.

  • Was ist Markdown und warum sollte man es verwenden?
  • Wie formatiere ich Inhalte in Markdown?
  • Wo findet Markdown überall Anwendung?
  • Wo liegen die Grenzen von Markdown?

Was ist Markdown?

  • vereinfachte Auszeichnungssprache
  • Erstveröffentlichung: 2004
  • Entwickler: John Gruber / Aaron Swartz
  • Dateiendung: *.md
  • MIME-Type: text/markdown
  • zunächst vorwiegend im Bereich der Software- und Webentwicklung genutzt (z.B. GitHub)
  • mittlerweile auch entwicklungsferne Einsatzgebiete (z.B. Obsidian)

Warum sollte man Markdown verwenden?

  • menschenlesbar
  • nicht-proprietär: Markdown ist einfach Text
  • einfach zu erlernen
  • unabhängig vom Betriebssystem nachnutzbar
  • nicht gebunden an bestimmte Software bzw. Tools
  • geringe Fehleranfälligkeit, einfache Korrekturen
  • einfache Konvertierung in viele gängige Formate (z.B. PDF, HTML)
  • Konzentration auf Inhalt, nicht auf Formatierung, gut für die Dokumentation

Wie verwende ich Markdown?

einfachste Verwendungsmöglichkeit

jeder einfache, bereits integrierte Texteditor Ihres Betriebssystems:

Nachteil: Keine Komfortfunktionen oder Preview!

Markdown im Editor ohne Preview

Wie es mit Preview aussehen könnte

Kostenfreie Markdown-Editoren mit erhöhtem Funktionsumfang

Reine Markdown-Editoren:

Code-Editoren:

Wie formatiere ich Inhalte in Markdown?

Überschriften
Markdown
# Überschrift 1

## Überschrift 2

### Überschrift 3

#### Überschrift 4

Wichtig:

  • Leerzeile vor und nach Überschrift
  • Leerzeichen nach "#"
HTML
<h1>Überschrift 1</h1>

<h2>Überschrift 2</h2>

<h3>Überschrift 3</h3>

<h4>Überschrift 4</h4>
Output

Überschrift 1

Überschrift 2

Überschrift 3

Überschrift 4

Absätze
Markdown
Dies ist ein Absatz. Er 
besteht aus mehreren Zeilen

Und dies ist ein weiterer
Absatz aus mehreren Zeilen,
ein sehr schöner Absatz.

Wichtig:

  • Absätze werden durch eine Leerzeile getrennt.
  • Einrückungen vor einem Absatz sind nicht erlaubt.
HTML
<p>Dies ist ein Absatz. Er 
besteht aus mehreren Zeilen
</p>

<p>Und dies ist ein weiterer
Absatz aus mehreren Zeilen,
ein sehr schöner Absatz.
</p>
Output

Dies ist ein Absatz. Er besteht aus mehreren Zeilen

Und dies ist ein weiterer Absatz aus mehreren Zeilen, ein sehr schöner Absatz.

Zeilenumbrüche
Markdown
Dies ist die erste Zeile.  
Dies ist die zweite Zeile.

Wichtig:

  • Um einen Zeilenumbruch zu erzeugen, setze zwei Leerzeichen nach der Zeile und nutze dann "Enter".
HTML
<p>Dies ist die erste Zeile.<br>
Dies ist die zweite Zeile.</p>
Output

Dies ist die erste Zeile.
Dies ist die zweite Zeile.

Hervorhebungen
Markdown
**Dies** ist Fettdruck.
__Dies__ auch.
Im W**or**t jedoch nur so.


*Dies* ist Kursivdruck.
_Dies_ auch.
Im W*or*t jedoch nur so.


***Dies*** ist kursiv und fett.
___Dies___ auch.
Im W***or***t jedoch nur so.
HTML
<strong>Dies</strong> ist Fettdruck.
<strong>Dies</strong> auch.
Im W<strong>or</strong>t jedoch nur so.


<em>Dies</em> ist Kursivdruck.
<em>Dies</em> auch.
Im W<em>or</em>t jedoch nur so.


<em><strong>Dies</strong></em> 
ist kursiv und fett.
<em><strong>Dies</strong></em> auch.
Im W<em><strong>or</strong></em>t
jedoch nur so.
Output

Dies ist Fettdruck.
Dies auch.
Im Wort jedoch nur so.

Dies ist Kursivdruck.
Dies auch.
Im Wort jedoch nur so.

Dies ist kursiv und fett.
Dies auch.
Im Wort jedoch nur so.

Ordered Lists
Markdown
1. Punkt 1
2. Punkt 2
    1. Unterpunkt 1
    2. Unterpunkt 2
3. Punkt 3

Wichtig:

  • Ordered List muss mit 1 beginnen, danach ist die Reihenfolge egal.
  • Für Unterpunkte doppelte Einrückungen nutzen.
  • Nummer für Unterkategorien (z.B. 2.1) sind nicht möglich.
HTML
<ol>
  <li>Punkt 1</li>
  <li>Punkt 2</li>
    <ol>
      <li>Unterpunkt 1</li>
      <li>Unterpunkt 2</li>
    </ol>
  <li>Punkt 3</li>
</ol>
Output
  1. Punkt 1
  2. Punkt 2
    1. Unterpunkt 1
    2. Unterpunkt 2
  3. Punkt 3
Unordered Lists
Markdown
- Punkt 1
- Punkt 2
    - Unterpunkt 1
    - Unterpunkt 2
- Punkt 3

Wichtig:

  • Unordered Lists werden mit -, * oder + erzeugt.
  • Für Unterpunkte doppelte Einrückungen nutzen.
HTML
<ul>
  <li>Punkt 1</li>
  <li>Punkt 2</li>
    <ul>
      <li>Unterpunkt 1</li>
      <li>Unterpunkt 2</li>
    </ul>
  <li>Punkt 3</li>
</ul>
Output
  • Punkt 1
  • Punkt 2
    • Unterpunkt 1
    • Unterpunkt 2
  • Punkt 3
Bilder
Markdown
![Markdown-Logo](./bilder/markdown_logo_bw.png)
HTML
<img src="./bilder/markdown_logo_bw.png" 
alt="Markdown-Logo">
Output

Markdown-Logo

Links
Markdown
[HeFDI](www.hefdi.de)

Dies ist ein [Link](www.hefdi.de).
HTML
<a href="www.hefdi.de">HeFDI</a>

Dies ist ein 
<a href="www.hefdi.de">Link</a>.
Output

HeFDI

Dies ist ein Link.

Zitate
Markdown
> Dies ist ein Zitat.
>
> Mit zwei Absätzen.
>
>> Und einem Zitat im Zitat.
HTML
<blockquote>
  <p>Dies ist ein Zitat.</p>
  <p>Mit zwei Absätzen</p>
  <blockquote>
    <p>Und einem Zitat im Zitat</p>
  </blockquote>
</blockquote>
Output

Fußnoten
Markdown
Dies ist ein Text.[^1]

Dies ist ein zweiter Absatz.[^2]

[^1]: Dies ist die Fußnote.
[^2]: Dies ist die zweite Fußnote.
HTML
<p>Dies ist ein Text.
<a href="#footnote-1">[1]</a></p>
<p>Dies ist ein zweiter Absatz.
<a href="#footnote-2">[2]</a></p>

<p id="footnote-1">
[1] Dies ist die Fußnote.</p>
<p id="footnote-1">
[2] Dies ist die zweite Fußnote.</p>
Output

Code-Blöcke
Markdown

Dies ist kein Codeblock.

Dies ist ein Codeblock.

Im Text kann man auch einzelne Worte als Code darstellen.

Wichtig:

  • wird mit drei ` eingeleitet und beendet
  • innerhalb von Text nutzt man jeweils ein `
HTML
<p>Dies ist kein Codeblock.</p>
<pre>
  <code>
    Dies ist ein Codeblock
  </code>
</pre>
<p>
  Im Text kann man auch 
  einzelne Worte als Code
  darstellen.
</p>
Output

Dies ist kein Codeblock.

Dies ist ein Codeblock.

Im Text kann man auch einzelne Worte als Code darstellen.

Character Escapes
Markdown
Man kann funktionale Zeichen
mit einem Backslash ohne ihre
Funktion darstellen (escapen), 
z.B.\[Link\]\(Adresse\).
HTML
Man kann funktionale Zeichen
mit einem Backslash ohne ihre
Funktion darstellen (escapen), 
z.B. &#91;Link&#93;&#40;Adresse&#41;.
Output

Man kann funktionale Zeichen mit einem Backslash ohne ihre Funktion darstellen (escapen), z.B. [Link](Adresse).

Mathematische Formeln
Markdown
Mathematische Gleichungen
im Text: $ax^2+bc+c$.

Oder als Blöcke:
$$ I_{xx}=\int\int_Ry^2f(x,y)\cdot{}dydx $$

$$
f(x) =
  \int_{-\infty}^\infty
  \hat f(\xi)\,e^{2 \pi i \xi x}
  \,d\xi
$$
HTML
<script type="text/javascript" 
  id="MathJax-script" async
  src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js">
</script>
<p>Mathematische Gleichungen
im Text: \(ax^2+bc+c$\).</p>
  
<p>Oder als Blöcke:
$$ I_{xx}=\int\int_Ry^2f(x,y)\cdot{}dydx $$
  
$$
f(x) =
  \int_{-\infty}^\infty
  \hat f(\xi)\,e^{2 \pi i \xi x}
  \,d\xi
$$
</p>
Output

Mathematische Gleichungen
im Text: .

Oder als Blöcke:

Diagramme mit Mermaid
Markdown
flowchart TD;
  A[Start]-->B[Entscheidung 1];
  A-->C[Entscheidung 2];
  B-->D[Ende];
  C-->D;
HTML
<script type="module">
  import mermaid from 'https://cdn.jsdelivr.
  net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
</script>
<pre class="mermaid">
  flowchart TD;
    A[Start]-->B[Entscheidung 1];
    A-->C[Entscheidung 2];
    B-->D[Ende];
    C-->D;
</pre>
Output
flowchart TD; A[Start]-->B[Entscheidung 1]; A-->C[Entscheidung 2]; B-->D[Ende]; C-->D;

Wo findet Markdown überall Anwendung?

Note-Taking Apps

Joplin

Obsidian

Code-Dokumentation

Jupyter Notebooks

Versionsverwaltung

GitLab

GitHub

Dokumentkonvertierung

Pandoc

Wissenschaftliches Schreiben

Zettlr

Präsentationen

Reveal.js

Marp

React + MDX Deck

Wo liegen die Grenzen von Markdown?

  • komplexe Layouts (z.B. bei der Positionierung von Elementen oder der Erstellung von komplexen Tabellen)
  • Anpassung typografischer Eigenschaften (Schriftgröße, Schriftart, Zeilenabstände)
  • Textfluss um Grafiken
  • animiertes oder multimediales Material
  • interaktive Elemente

- Begrüßen - Sich vorstellen - Was ist HeFDI? - Was ist die HeFDI Data Week? - Auf ELN-Track morgen hinweisen und auf Q&A-Session - Track eröffnen (HeFDI Data Week, HeFDI, Überblick über Vorträge) - Hintergründe für den Vortrag erläutern (HeFDI Data School, eigene Hintergründe: Ziel ist nicht die Missionierung, sondern zu zeigen, wo Markdown vielleicht auch einfach besser geeignet ist als ein Word-Dokument)

- Zielgruppe definieren - Ziele erläutern - Aber auch darauf eingehen, dass Markdown nicht die Lösung für alles ist.

Markdown bedeutet in diesem Fall übersetzt so viel wie "Abschrift". MIME-Type bedeutet Multipurpose Internet Mail Extension. Man bezeichnet es häudig auch als Content-Type, da dieser die Daten im Body von Dokumenten im Internet klassifiziert, um dem Webserver mitzuteilen, welche Daten er an den Browser senden soll. Hauptgrund für die Entwicklung von Markdown war laut Gruber, dass er für seine Webseiten immer wieder Texte in nervigem HTML verfassen musste. Er wollte eine einfache Lösung, ähnlich dem Schreiben einer E-Mail, um Webtexte zu produzieren.

Vor allem im Bereich des Codens ist Markdown neben der Codekommentierung eigentlich unerlässlich, da in einem Team mit Markdown auch die entsprechende Dokumentation mitversioniert werden kann, da es rein textbasiert ist. Es gibt auch noch zusätzliche Vorteile, wie beispielsweise einen extrem großen Support durch die Community.

Pulsar-Edit ist ein Community-Folgeprojekt zum sehr beliebten, aber eingestellten Markdown-Editor "Atom".

Wichtig: Vergessen Sie nicht das Leerzeichen zwischen der Raute und der eigentlichen Überschrift. Setzen Sie außerdem immer Leerzeilen vor und nach den Überschriften, bevor Sie weitere Überschriften oder Absätze einfügen, sonst gibt es Probleme beim Rendern des Output.

Das <p>-Element in HTML steht für das Wort "paragraph"

mermaid.js

Komplexe Layouts: Markdown ist hauptsächlich auf einfache Textformatierung ausgelegt und unterstützt keine komplexen Layoutoptionen wie mehrspaltige Tabellen oder komplexe Positionierung von Elementen. Feinere Typografie: Markdown bietet begrenzte Optionen für die Steuerung der Typografie, wie Schriftarten, Schriftgrößen oder Zeilenabstände. Es ist darauf ausgelegt, einfachen Text ohne detaillierte Formatierungen darzustellen. Grafiken mit Textfluss: Obwohl Markdown die Einbindung von Bildern unterstützt, gibt es keine Möglichkeit, den Textfluss um die Bilder herum anzupassen. Das bedeutet, dass Bilder in Markdown-Dokumenten normalerweise nur neben dem Text angezeigt werden können. Animiertes oder multimediales Material: Markdown ist auf statische Inhalte beschränkt und bietet keine Möglichkeit, animierte Grafiken oder Multimedia-Inhalte wie Videos oder Audiodateien einzufügen. Interaktive Elemente: Markdown kann statische Inhalte darstellen, aber es bietet keine direkte Unterstützung für interaktive Elemente wie Formulare, Buttons oder andere dynamische Elemente.