--- status: final --- :::{raw} latex \clearpage ::: :::{index} single: Markdown ::: :::{index} single: MySt ::: (MyST)= (Markdown)= # 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 {program}`Sphinx` Toolchain. Sie erlaubt das erstellen u. a. von druckfertigen PDFs, Webseiten und eBooks. :::{figure} Sphinx-Compile.png Kompilation: Aus dem Klartext erzeugt der Interpreter (Compiler) unter Zuhilfenahme der Stil-Definitionen die verschiedenen Ausgabeformate (Produkte). ::: :::{admonition} 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. :::{list-table} Markdown-Syntaxübersicht :header-rows: 1 :stub-columns: 1 :widths: 20 40 40 * - Funktion - Syntax - Ergebnis * - Einfache Hervorhebung - ``` Ich bin *hervorgehoben* ``` - Ich bin *hervorgehoben* * - Starke Hervorhebung - ``` Ich bin **stark hervorgehoben** ``` - Ich bin **stark hervorgehoben** * - Überschriften - ```markdown # Überschrift Ebene 1 ## Überschrift Ebene 2 ``` - * - Liste - ```markdown - Erster Punkt - Zweiter Punkt - Unterpunkt - Noch einer - Dritter Punkt ``` - - Erster Punkt - Zweiter Punkt - Unterpunkt - Noch einer - Dritter Punkt * - Aufzählung - ```markdown 1. Erstens 1. Unterpunkt 2. Außerdem ... 2. Zweitens ``` - 1. Erstens 1. Unterpunkt 2. Außerdem ... 2. Zweitens * - Defintionsliste - ```markdown Begriff : Die Erklärung ``` - Begriff : Die Erklärung * - Bild - ```markdown ![Ein grün-gelbes Schachbrett](a.png) ``` - ![Ein grün-gelbes Schachbrett](a.png) * - Bild mit Beschreibung - ```markdown :::{figure} a.png Ein grün-gelbes Schachbrett ::: ``` - :::{figure} a.png Ein grün-gelbes Schachbrett ::: * - Link - ```markdown [Link zu Example GmbH](https://example.com) ``` - [Link zu Example GmbH](https://example.com) * - Zitat - ```markdown > Blockquote ``` - > Blockquote * - Trennlinie - ```markdown --- ``` - ![alt text](HR.png) * - Code - ``` Die Barcodenummer ist `123123`! ``` - Die Barcodenummer ist `123123`! * - Mathematik - ```markdown $I = \frac{U}{R}$ ``` oder ```markdown {math}`I = \frac{U}{R}` ``` - $I = \frac{U}{R}$ Anm.: Die Syntax folgt der [LaTeX-Mathematik-Syntax](https://www.grund-wissen.de/informatik/latex/mathematischer-formelsatz.html). ::: ## Basis-Markdown ::::::{admonition} Beispiel: Basis-Markdown ::::{code} 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 : ::::{code} markdown Text {rollenname}`Inhalt` :::: :::{important} 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 {kbd}`ß`- und {kbd}`Backspace`-Taste, über dem Akut ({kbd}`´`) → {kbd}`Shift+´` ::: :::{list-table} Beispiele für Rollen :header-rows: 1 :stub-columns: 1 * - Funktion - Rolle - Beispiel * - Abkürzung - `{abbr}` - ``` {abbr}`MRT (Magnetresonanztomographie)` ``` * - Querverweis - `{ref}` - ``` {ref}`Beschreibung