---
author: B. A. Sylla
category: Howto
date: 2025-05-02
language: de
tags: Markdown
---
Howto - Markdown mit dem Myst Parser für Sphinx Dokus
=====================================================
Die [Doku zum Myst-Parser](https://myst-parser.readthedocs.io/en/latest/) beschreibt die folgenden Punkte noch genauer.
## Sphinx-Meta-Felder
Siehe [Myst-Doku](https://myst-parser.readthedocs.io/en/latest/faq/index.html#sphinx-specific-page-front-matter)
```md
---
copyright: B. A. Sylla
orphan: true
tocdepth: 3
---
```
## Änderungsdatum, Wortananzahl und Lesedauer
Siehe [Myst-Doku](https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html#insert-the-date-and-reading-time)
## Table of Contents
Siehe [Myst-Doku](https://myst-parser.readthedocs.io/en/latest/syntax/organising_content.html#document-structure)
Siehe [TODO](https://documatt.com/restructuredtext-reference/element/contents.html)
```{contents} Table of Contents
:depth: 3
:backlinks: none
```
## Headings h2 bis h6
Siehe [Myst-Doku](https://myst-parser.readthedocs.io/en/latest/syntax/typography.html#headings)
``` md
## h2 Heading
### h3 Heading
#### h4 Heading
##### h5 Heading
###### h6 Heading
```
## Typographische Ersetzungen
Siehe [Myst-Doku](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#typography)
Enable typographer option to see result.
(c) (C) (r) (R) (tm) (TM) (p) (P) +-
test.. test... test..... test?..... test!....
!!!!!! ???? ,, -- ---
"Smartypants, double quotes" and 'single quotes'
## Text-Formatierung
Siehe [Myst-Doku](https://myst-parser.readthedocs.io/en/latest/syntax/typography.html#inline-text-formatting)
**This is bold text**
__This is bold text__
*This is italic text*
_This is italic text_
~~Strikethrough~~
## Links
| Markup | intern | extern | internet | Anmerkung
|--------|--------|--------|----------|----------
| | | | |
| | | | |
| | | | |
## Zitat-Blöcke
Siehe [Myst-Doku](https://myst-parser.readthedocs.io/en/latest/syntax/typography.html#quotations)
> Blockquotes can also be nested...
>> ...by using additional greater-than signs right next to each other...
> > > ...or with spaces between arrows.
{attribution="Hamlet act 4, Scene 5"}
> We know what we are, but know not what we may be.
## Spezielle Blöcke
TODO
:::{note}
This text is **standard** *Markdown*
:::
:::{important}
Test
:::
```{warning}
Here's my warning
```
```{error}
Here's my error
```
:::{admonition} Yep another admonition
Test
:::
## HTML Admonitons
TODO
This is the **title**
This is the *content*
Some **content**
A *title*
Paragraph 1
Paragraph 2
## Listen
Siehe [Myst-Doku](https://myst-parser.readthedocs.io/en/latest/syntax/typography.html#bullet-points-and-numbered-lists)
### Ungeordnete listen
+ Create a list by starting a line with `+`, `-`, or `*`
+ Sub-lists are made by indenting 2 spaces:
- Marker character change forces new list start:
* Ac tristique libero volutpat at
+ Facilisis in pretium nisl aliquet
- Nulla volutpat aliquam velit
+ Very easy!
### Geordnete Listen
1. Lorem ipsum dolor sit amet
2. Consectetur adipiscing elit
3. Integer molestie lorem at massa
1. You can use sequential numbers...
1. ...or keep all the numbers as `1.`
Start numbering with offset:
57. foo
1. bar
## Definition Lists
Siehe [Myst-Doku](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#definition-lists)
Term 1
: Definition
Term 2
: Definition
## Todo-Listen
Siehe [Myst-Doku](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#task-lists)
The following todo list has attributes `#id1` and `.class1`. But the class atribute does not work. Attribute blocks are still beta.
But you can add something like `` to list items like in the first "item A".
{#id1 .class1}
- [x] item A
- [ ] item B
## Attribut-Blöcke
Siehe [Myst-Doku](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#block-attributes)
{#mypara .bg-warning}
Here is a paragraph with attributes `#mypara` and `.bg-warning`.
## Quellcode-Blöcke
Siehe [Myst-Doku](https://myst-parser.readthedocs.io/en/latest/syntax/code_and_apis.html)
Quellcode wird per [highlight.js](https://highlightjs.org/) gefärbt. Es gibt eine [Liste](https://highlightjs.readthedocs.io/en/latest/supported-languages.html) welche Sprachen unterstützt werden.
Inline `code`
Indented code
// Some comments
line 1 of code
line 2 of code
line 3 of code
Block code "fences"
```
Sample text here...
```
Syntax highlighting
``` js
var foo = function (bar) {
return bar++;
};
console.log(foo(5));
```
```{code-block} cpp
:caption: This is a caption
:linenos: true
#include // std::cout
int main() {
std::cout << "Hello world!" << std::endl;
return EXIT_SUCCESS;
}
```
## Mathe-Formeln
Siehe [Myst-Doku](https://myst-parser.readthedocs.io/en/latest/syntax/math.html)
### Mit `:::{math}...:::` für Block-Formeln
```{math}
:label: mymath
(a + b)^2 = a^2 + 2ab + b^2
(a + b)^2 &= (a + b)(a + b) \\
&= a^2 + 2ab + b^2
```
## $\LaTeX$-Mathe-Formeln
Siehe [Myst-Doku](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#math-shortcuts)
### Mit `$...$` für Inline-Formeln
Diese Formel $x_{hey}=it+is^{math}$ ist im Text.
### Mit `$$...$$ (1)` für Block-Formeln
Das (1) ist optional.
$$
y & = ax^2 + bx + c \\
f(x) & = x^2 + 2xy + y^2
$$ (1)
### Mit `\begin...\end` für Block-Formeln
Siehe [Myst-Doku](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#direct-latex-math)
\begin{gather*}
a_1=b_1+c_1\\
a_2=b_2+c_2-d_2+e_2
\end{gather*}
\begin{align}
a_{11}& =b_{11}&
a_{12}& =b_{12}\\
a_{21}& =b_{21}&
a_{22}& =b_{22}+c_{22}
\end{align}
## Bilder
```{image} /_static/doom_icon.png
:alt: Alternativtext2
:align: center
```
```{figure} /_static/doom_icon.png
:alt: Alternativtext3
:align: left
This is a caption in __*Markdown*__
```
:::{figure-md}
This is a caption in __*Markdown*__
:::
## Weitere Steuerelemente mit `sphinx_design`: Cards, Badges, Buttons, Drobdowns, Grid, Icons und Tabs
Siehe [sphinx-design](https://sphinx-design.readthedocs.io)
TODO
## Diagramme mit Mermaid.js
Siehe [Mermaid.js-Tutorials](https://mermaid.js.org/ecosystem/tutorials.html)
```{mermaid}
graph LR;
id_A(20)
id_AB(40)
id_B(60)
id_C(10)
id_CD(15)
id_D(30)
id_A --- id_AB --- id_B
id_A -- realistic --> id_D
id_B -- realistic --> id_C
id_C --- id_CD --- id_D
id_A --- id_C
id_B --- id_D
subgraph one
a --- b --- c
end
subgraph two
d --- e --- f
end
a --- f
b --- e
c --- d
```
```{mermaid}
block-beta
columns 1
block:ID1
Decision1{{"Sampling steps:"}}
style Decision1 fill:transparent,stroke:transparent
A["20"]
B["30"]
C["40"]
D["50"]
E["60"]
end
space
block:ID2
Decision2{{"CFG Steps:"}}
style Decision2 fill:transparent,stroke:transparent
F["10"]
G["12"]
H["15"]
I["20"]
J["30"]
end
A --> J
B --> I
C --> H
D --> G
E --> F
```
## Diagramme mit PlantUML
TODO
## Jupyter-Notebooks in Ablog mit `nbsphinx`
Siehe [nbsphinx](https://nbsphinx.readthedocs.io) und [Ablog-Doku](https://ablog.readthedocs.io/en/stable/manual/notebook_support.html)
Mit Diesem Mogul kann man wohl nur ganze Jupyter-Notebooks mit der Endung `.ipynb` statt `.rst` oder `.md` als Blog-Artikel nutzen.
Dazu muss das Notebook bspw. mit JupyerLab erstellt und danach mit einem Editor modifiziert werden. Denn es braucht für einen Blog-Artikel Metadaten. JupyterLab erstellt bei allen Zellen IDs, was für Ablog nicht weiter schlimm ist.
### Erste Zelle: Titel \ für den Blog-Artikel
Das kann in JupyterLab erstellt worden sein und nicht erst hinterher mit dem Editor.
```json
{
"cells": [
{
"cell_type": "markdown",
"id": "dd2628aa-71e6-47df-8932-01d4ded8d0e3",
"metadata": {},
"source": [
"# Beispiele mit Jupyter"
]
},
//...
}
```
### Zweite Zelle: Metadaten für den Blog-Artikel
Die zweite Zelle kann man theoretisch auch in JupyterLab erstellen, aber die Zeile `"raw_mimetype": "text/restructuredtext"` wäre dann leer. Die muss unbedingt drin sein. Sonst erkennt Ablog das Notebook nicht als Blog-Artikel.
```json
{
"cell_type": "raw",
"metadata": {
"raw_mimetype": "text/restructuredtext"
},
"source": [
".. post:: 2025-05-26\n",
" :author: B. A. Sylla\n",
" :category: Howto\n",
" :language: de\n",
" :tags: Jupyter"
]
},
```
Die zweite Zelle mit Metadaten ist dann in der fertigen HTML nicht mehr zu sehen. Was eigentlich Blödsinn ist, denn Metadaten für Markdown-Dateien werden auch ganz Forne und nicht nach dem Titel angegeben. Bei Jupyter-Notebooks wollen die Entwickler von Ablog das aber so, aus nichterklärtem Grund.
```{note}
Es gibt eine [Demo-Seite](draft_demo_seite.ipynb) die aus einem `.ipynb` erstellt wurde. Sie rendert aber nur richtig, wenn Ablog mit `nbsphinx` und Pandoc (Shell-Tools) zum Erstellen der Seite verwendet wurde und nicht Sphinx mit `myst-nb`. Das Notebook wir nicht einmal von Ablog erstellt. Denn Ablog übernimmt einfach die Ausgabe von JupyterLab die in dem Notebook drin steckt, um daraus HTML zu erzeugen.
```
## Jupyter-Notebooks in Sphynx mit `myst-nb`
```{note}
Wenn diese Seite mit Ablog erstellt wurde, dann sieht man zwischen den nachfolgenden Absätzen keine Jupyter-Ausgabe. Das Folgende rendert nur richtig, wenn nicht Ablog mit `nbsphinx` und Pandoc (Shell-Tools), sondern Sphinx mit `myst-nb` zum Erstellen dieser Seite verwendet wurde. Diese Jupyter-Zellen werden von Sphinx mindestens einmal erstellt oder jedes mal, falls `nb_execution_mode = "force"` in der `conf.py` steht, statt `"auto"`. Wenn man die Ausgabe des Notebooks nur übernehmen will, statt zu neu rendern, muss man `"off"` nutzen. Was aber auf Zellen in Markdown-Dateien keine Wirkung hat, sondern nur auf ganze Notebook-Dateien mit der Endung `.ipynb`.
```
Siehe [MyST-NB-Doku](https://myst-nb.readthedocs.io/en/latest/authoring/basics.html) und [Read-The-Docs-Doku](https://docs.readthedocs.com/platform/latest/guides/jupyter.html)
### Jupyter-Notebooks nutzen
TODO: Demo-Seite wie im vorigen Beispiel nutzen, die aber anders als dort keine Metadaten haben soll.
### Jupyter-Zelle in Markdown nutzen
Man kann Code-Zeilen nummerieren.
```{code-cell} ipython3
---
mystnb:
number_source_lines: true
---
a = 1
b = 2
c = 1
```
Ein-/Ausgabe für stdin, stdout, stderr ist unterdrückbar. Der nachfolgende Code wird dadurch gar nicht angezeigt, sondern nur das Ergebnis.
```{code-cell} ipython3
:tags: [remove-input,remove-stdout,remove-stderr]
import pandas, sys
print("this is some stdout")
print("this is some stderr", file=sys.stderr)
# but what I really want to show is:
pandas.DataFrame({"column 1": [1, 2, 3]})
```
LaTeX-Formeln sind in Jupyter-Notebooks möglich.
```{code-cell} ipython3
from IPython.display import Latex
Latex("\\int_{-\\infty}^\\infty e^{-x²}dx = \\sqrt{\\pi}")
```
Widgets können zwar gerendert werden, ahebn aber keine Funktion in Sphinx/Ablog.
```{code-cell} ipython3
import ipywidgets as w
from IPython.display import display
a = w.IntSlider()
b = w.IntText()
w.jslink((a, "value"), (b, "value"))
display(a, b)
```
Charts mit Matplotlib sind auch möglich, nur leider nicht interaktiv.
```{code-cell} ipython3
%%time
import numpy as np
from matplotlib import pyplot
%matplotlib inline
x = np.linspace(1E-3, 2 * np.pi)
pyplot.plot(x, np.sin(x) / x)
pyplot.plot(x, np.cos(x))
pyplot.grid()
```
## Fußnoten
Siehe [Myst-Doku](https://myst-parser.readthedocs.io/en/latest/syntax/typography.html#footnotes)
- This is a manually-numbered footnote reference.[^3]
- This is an auto-numbered footnote reference.[^myref]
[^myref]: This is an auto-numbered footnote definition.
[^3]: This is a manually-numbered footnote definition.
## Fin