MyST-Markdown Kurzanleitung

17.6.2. MyST-Markdown Kurzanleitung#

Was ist Klartext?#

Klartext (Engl.: Plain text) ist Text, der ausschließlich aus lesbaren Zeichen besteht und keine Formatierungen oder eingebetteten Objekte enthält. Er enthält nur den eigentlichen textuellen Inhalt (z. B. Buchstaben, Zahlen, Satzzeichen) ohne Informationen über Formatierungen wie Schriftart, Größe, Farbe oder Layout.

Auszeichnungssprachen

… können Befehle definieren, um die Funktionalität von Klartext zu erweitern, z. B. um Hervorhebungen oder Ähnliches zu ermöglichen.

Semantik

Darunter versteht man den eigentlichen Inhalt bzw. Meta-Informationen (“Das ist eine Hervorhebung”, “Das ist ein Produkname”, …)

Syntax

Definiert die erforderliche Schreibweise um ein bestimmtes Ergebnis zu Erhalten.

Kompilation

Für die eigentliche Formatierung ist ein zusätzlicher Schritt nötig, welcher aus dem Klartext die eigentlichen formatierten Produkte (PDF-Dateien, Webseiten etc.) herstellt (Kompilation). Dabei werden von einem Interpreter (Compiler) die Definitionen durch die Auszeichnungssprache im Dokument mit festgelegten Layout- und Stil-Definitionen verglichen und zu der eigentlichen, dem Ausgabeformat entsprechenden, Formatierung überführt. Dies ist sinnvoll, da die Formatierungsmöglichkeiten wesentlich von der gewünschten Zielplattform abhängen (Druck: z. B. “mache Hervorhebungen fett”, Online: z. B.: “Mache Hervorhebungen fett und dunkelblau”, …).

Der Compiler für dieses Projekt ist die Sphinx Toolchain. Sie erlaubt das erstellen u. a. von druckfertigen PDFs, Webseiten und eBooks.

../../../_images/Sphinx-Compile.png

Fig. 258 Kompilation: Aus dem Klartext erzeugt der Interpreter (Compiler) unter Zuhilfenahme der Stil-Definitionen die verschiedenen Ausgabeformate (Produkte).#

Synopsis

  • Klartext erlaubt die Trennung von Inhalt und Format

  • Layout- und Stildefintionen definieren die Formatierung des Inhaltes für die unterschiedlichen Ausgabeformate.

  • Die Kompilation erstellt aus den Inhalten und den Stildefinitionen die formatierten Endprodukte.

Durch die Trennung von Inhalt und Formatierung können aus dem gleichen Inhalt unterschiedliche Produkte (Druck, Online, …) erstellt werden.

Was ist Markdown?#

Markdown (MD) ist eine Auszeichnungssprache, die entwickelt wurde, um Klartext mit einfacher, gut lesbarer Syntax zu formatieren. Im Gegensatz zu komplexeren Formaten wie HTML oder LaTeX bleibt der Quelltext nahezu so lesbar wie der fertige Text. Formatierungen wie Überschriften, Listen, Hervorhebungen oder Links werden durch wenige, intuitive Zeichen dargestellt (z. B. #, *, []()). Markdown wird häufig für Dokumentationen, Webseiten, wissenschaftliche Texte und Notebooks verwendet, da es einfach zu schreiben, plattformunabhängig und gut automatisierbar ist. MyST (Markedly Structured Text) erweitert Markdown um Funktionen für wissenschaftliches und technisches Schreiben. Es ergänzt Markdown um Direktiven, Rollen, Querverweise, Mathematik und strukturierte Metadaten.

Tab. 123 Markdown-Syntaxübersicht#

Funktion

Syntax

Ergebnis

Einfache Hervorhebung

 
Ich bin *hervorgehoben*

Ich bin hervorgehoben

Starke Hervorhebung

 
Ich bin **stark hervorgehoben**

Ich bin stark hervorgehoben

Überschriften

 
# Überschrift Ebene 1

## Überschrift Ebene 2

Liste

 
-   Erster Punkt
-   Zweiter Punkt
    -   Unterpunkt
    -   Noch einer
-   Dritter Punkt

  • Erster Punkt

  • Zweiter Punkt

    • Unterpunkt

    • Noch einer

  • Dritter Punkt

Aufzählung

 
1.  Erstens
    1.  Unterpunkt
    2.  Außerdem ...
2.  Zweitens

  1. Erstens

    1. Unterpunkt

    2. Außerdem …

  2. Zweitens

Defintionsliste

 
Begriff
:   Die Erklärung
Begriff

Die Erklärung

Bild

 
![Ein grün-gelbes Schachbrett](a.png)

Ein grün-gelbes Schachbrett

Bild mit Beschreibung

 
:::{figure} a.png

Ein grün-gelbes Schachbrett
:::
../../../_images/a.png

Fig. 259 Ein grün-gelbes Schachbrett#

Link

 
[Link zu Example GmbH](https://example.com)

Link zu Example GmbH

Zitat

 
>   Blockquote

Blockquote

Trennlinie

 
---

alt text

Code

 
Die Barcodenummer ist `123123`!

Die Barcodenummer ist 123123!

Mathematik

 
$I = \frac{U}{R}$

oder

{math}`I = \frac{U}{R}`

\(I = \frac{U}{R}\)

Anm.: Die Syntax folgt der LaTeX-Mathematik-Syntax.

Basis-Markdown#

Beispiel: Basis-Markdown

# Überschrift Ebene 1
## Überschrift Ebene 2
### Überschrift Ebene 3

*hervorgehoben*
**stark hervorgehoben**

-   Liste
-   Liste

1.  Aufzählung
2.  Aufzählung

[Link](https://example.com)

Rollen (Inline-Elemente)#

Rollen dienen zur erweiterten Formatierung innerhalb einer Zeile, bzw. können spezielle Funktionen haben wie z. B. das Einfügen eines Querverweises.

Allgemeine Syntax
Text {rollenname}`Inhalt`

Wichtig

Der Accent grave (Gravis, `) ist ein eigenständiges Zeichen und nicht mit einem Anführungsstrich bzw. Apostroph gleichzusetzen!

Auf deutschen Tastaturen befindet er sich zwischen der ß- und Backspace-Taste, über dem Akut (´) → Shift+´

Tab. 124 Beispiele für Rollen#

Funktion

Rolle

Beispiel

Abkürzung

{abbr}

{abbr}`MRT (Magnetresonanztomographie)`

Querverweis

{ref}

{ref}`Beschreibung <label>`

Nummerierter Querverweis

{numref}

{numref}`Beschreibung <label>`

Verweis auf Term

{term}

{term}`term`

Verweis auf Formel

{eq}

{eq}`FormelEinstein`

Bild

{image}

{image}`a.png`

Mathematik

{math}

{math}`E = mc^2`

 

Direktiven (Block-Elemente)#

Direktiven dienen der Formatierung von abgesetzten Blöcken und haben meistens spezielle Funktionen (Textboxen, Einfügen von Bildern oder Tabellen etc.). Sie beginnen mit einem Fence (:::) und einem Namen in geschweiften Klammern und enden in einer der folgenden Zeilen wiederum mit :::. Alles was zwischen den Fences steht wird von der Direktive erfasst. Direktiven können auch ineinander verschachtelt werden, dabei erhöht sich die Anzahl der : der jeweiligen Direktive damit es eindeutig bleibt, welcher Fence welche Direktive beendet. Direktiven können ein Argument und darüber hinaus mehrere Optionen haben.

Allgemeine Syntax
:::{name} Argument
:Option1: Wert
:Option2: Wert

Inhalt
:::

Häufig verwendete Direktiven sind:

  • image … für unbeschriftete Bilder

  • figure … für beschriftete Bilder

  • math … für Formeln

  • admonition … für Boxen

Beispiel: Abbildung

:::{figure} a.png
:align: center
:width: 50%

Bildunterschrift
:::
../../../_images/a.png

Fig. 260 Bildunterschrift#

Definitionslisten

Definitionslisten dienen zur Darstellung von Begriffen mit zugehörigen Definitionen. Sie eignen sich besonders für Glossare, Verzeichnisse oder strukturierte Erklärungen. Eine Definitionsliste besteht aus einem Begriff (Term) und einer oder mehreren Definitionen:

Begriff
:   Definition

Beispiel: Definition List

Reanimation
:   Wiederbelebungsmaßnahmen zur Wiederherstellung von Atmung und Kreislauf

Hypoxie
:   Sauerstoffmangel im Gewebe
Reanimation

Wiederbelebungsmaßnahmen zur Wiederherstellung von Atmung und Kreislauf

Hypoxie

Sauerstoffmangel im Gewebe

Beispiel: Mehrzeilige Definition

Sepsis
:   Lebensbedrohliche Organdysfunktion infolge einer dysregulierten Immunantwort auf eine Infektion.
    Sie kann verschiedene Ursachen haben.

    Man kann ihr auch einen weiteren Absatz widmen.
Sepsis

Lebensbedrohliche Organdysfunktion infolge einer dysregulierten Immunantwort auf eine Infektion. Sie kann verschiedene Ursachen haben.

Man kann ihr auch einen weiteren Absatz widmen.

Beispiel: Mehrere Definitionen

Schock
:   Lebensbedrohlicher Zustand mit unzureichender Gewebeperfusion
:   Psychische Reaktion auf belastendes Ereignis
Schock

Lebensbedrohlicher Zustand mit unzureichender Gewebeperfusion

Psychische Reaktion auf belastendes Ereignis

Hinweise:

  • Der Begriff steht in einer eigenen Zeile

  • Die Definition beginnt mit :  

  • Einrückung ist entscheidend für die Struktur

  • Mehrere Definitionen sind möglich

Querverweise#

Mit Labels können Abschnitte, Abbildungen oder Gleichungen referenziert werden.

Tab. 125 Rollen für Querverweise#

Funktion

Rolle

Beispiel

Querverweis

{ref}

{ref}`Beschreibung <label>`

Nummerierter Querverweis

{numref}

{numref}`Beschreibung <label>`

Verweis auf einen Term in einem Glossar

{term}

{term}`term`

Verweis auf Formel

{eq}

{eq}`FormelEinstein`

Vorgehen

  1. Marke (Label) setzen: Dies ist abhängig davon, was referenziert werden soll (Überschrift, Bild, Tabelle etc.)

    • Label vor Überschrift setzen mittels (Labelname)=

      Erzeugt das Label Reanimation vor der eigentlichen Überschrift:

      (Referenz-erzeugen)=

# Referenz erzeugen

    • Direktiven (z.B. Bild, Tabelle, Formel) benennen: Dies geschieht mittels der Option :label: innerhalb der Direktive:

      :::{figure} a.png
:label: fig-beispiel

Bildunterschrift
:::

  2. Verweis erzeugen

    Siehe {ref}`Referenz-erzeugen`, oder siehe {ref}`Beipiel zum Erzeugen einer Referenz <Referenz-erzeugen>`.

Beispiel: Querverweis

Siehe {ref}`Referenz-erzeugen`, oder siehe {ref}`Beipiel zum Erzeugen einer Referenz <Referenz-erzeugen>`.

Siehe Querverweise, oder siehe Beipiel zum Erzeugen einer Referenz.

Tabellen#

MyST Markdown unterstützt mehrere Möglichkeiten zur Erstellung von Tabellen. Für strukturierte Inhalte ist die list-table-Tabelle vorteilhaft.

MyST list-table#

Die list-table-Direktive ist die flexibelste Methode und besonders für komplexe Inhalte geeignet.

Grundstruktur
:::{list-table} Titel der Tabelle
:header-rows: 1
:stub-columns: 1

*   -   Spalte 1
    -   Spalte 2
*   -   Wert A
    -   Wert B
*   -   Wert C
    -   Wert D
:::
Wichtige Regeln

  • Jede Tabellenzeile beginnt mit *

  • Jede Zelle beginnt mit -

  • Einrückung: 4 Zeichen pro Ebene

  • Tabellenüberschriften sind optional:

    • :header-rows: 1 definiert die Kopfzeile

    • :stub-columns: 1 definiert Titelspalten

Mehrzeilige Inhalte in Zellen

In list-table können Zellen komplexe Inhalte enthalten: strukturierte Inhalte innerhalb einer Zelle möglich.

Beispiel :

:::{list-table} Beispiel mit Listen
:header-rows: 1

*   -   Kategorie
    -   Beispiele
*   -   Atemmechanik
    -   -   Obere Atemwege
        -   Untere Atemwege
        -   Pneumothorax
:::

Typische Fehler

Fehler

  • Uneinheitliche Spaltenanzahl

  • Falsche Einrückung (nicht 4 Zeichen)

  • Fehlendes * für neue Zeile

  • Fehlendes - für Zellen

Klassische Markdown-Tabelle#

Einfache Tabellen können direkt mit Pipes (|) erstellt werden.

Grundstruktur
| Spalte 1 | Spalte 2 |
|----------|----------|
| Wert A   | Wert B   |
| Wert C   | Wert D   |
Eigenschaften

  • Schnell und übersichtlich

  • Gut für einfache Inhalte

  • Eingeschränkt bei komplexen Layouts

Wann welche Tabelle?#

Empfehlung

  • Markdown-Tabelle

    • Kleine, einfache Tabellen

  • list-table

    • Komplexe Inhalte

    • Mehrzeilige Zellen

    • Lehrbuch-/Dokumentationsprojekte

Bemerkung

Für strukturierte und umfangreichere Inhalte ist list-table meistens die bessere Lösung.

Mathematik#

Mathematik kann in der Zeile (inline) oder als abgesetzter Block dargestellt werden:

  1. In der Zeile:

    $E = mc^2$

  2. Als Block:

    ```{math}
E = mc^2
```

Beispiel: Mathematik

:::{math}
:label: FormelEinstein

E = mc^2
:::

Der Vorteil des Blocks ist, dass die Formel benannt und mit der Rolle `{eq}}` referenziert (siehe Formel {eq}`FormelEinstein`) werden kann.
(13)#\[E = mc^2\]

Der Vorteil des Blocks ist, dass die Formel benannt und mit der Rolle {eq} referenziert (siehe Formel (13)) werden kann.

Fußnoten#

Beispiel: Fußnote

Text mit Fußnote[^Bezeichner]

[^Bezeichner]: Text der Fußnote

Text mit Fußnote[1]

Frontmatter#

Frontmatter enthält Metadaten und steht am Anfang der Datei.

Beispiel: Frontmatter

---
title: Mein Dokument
authors:
  - name: Max Mustermann
date: 2025-03-30
status: final
---

Hier beginnt dann der eigentliche Text des Dokuments ...
Auf dieser Seite ...