Howto - Markdown mit dem Myst Parser für Sphinx Dokus

../../../_images/sphinx_in_egypt.jpg

Geändert: 2025-06-14 08:45:30, Wörter: 729, Lesedauer: 4 min

Die Doku zum Myst-Parser beschreibt die folgenden Punkte noch genauer.

Sphinx-Meta-Felder

Siehe Myst-Doku

---
copyright: B. A. Sylla
orphan: true
tocdepth: 3
---

Änderungsdatum, Wortananzahl und Lesedauer

Siehe Myst-Doku

Geändert: 2025-06-14 08:45:30, Wörter: 729, Lesedauer: 4 min

Table of Contents

Siehe Myst-Doku Siehe TODO

Headings h2 bis h6

Siehe Myst-Doku

## h2 Heading
### h3 Heading
#### h4 Heading
##### h5 Heading
###### h6 Heading

Typographische Ersetzungen

Siehe Myst-Doku

Enable typographer option to see result.

© © ® ® ™ ™ (p) (P) ±

test… test… test… test?.. test!..

!!! ??? , – —

“Smartypants, double quotes” and ‘single quotes’

Text-Formatierung

Siehe Myst-Doku

This is bold text

This is bold text

This is italic text

This is italic text

Strikethrough

Zitat-Blöcke

Siehe Myst-Doku

Blockquotes can also be nested…

…by using additional greater-than signs right next to each other…

…or with spaces between arrows.

We know what we are, but know not what we may be.

—Hamlet act 4, Scene 5

Spezielle Blöcke

TODO

Note

This text is standard Markdown

Important

Test

Warning

Here’s my warning

Error

Here’s my error

Yep another admonition

Test

HTML Admonitons

TODO

This is the title

This is the content

Note

Some content

A title

Paragraph 1

Paragraph 2

Listen

Siehe Myst-Doku

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

  4. You can use sequential numbers…

  5. …or keep all the numbers as 1.

Start numbering with offset:

  1. foo

  2. bar

Definition Lists

Siehe Myst-Doku

Term 1

Definition

Term 2

Definition

Todo-Listen

Siehe Myst-Doku

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 <done class="xyz"> to list items like in the first “item A”.

  • item A

  • item B

Attribut-Blöcke

Siehe Myst-Doku

Here is a paragraph with attributes #mypara and .bg-warning.

Quellcode-Blöcke

Siehe Myst-Doku

Quellcode wird per highlight.js gefärbt. Es gibt eine Liste 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

var foo = function (bar) {
    return bar++;
};

console.log(foo(5));
This is a caption
1#include <iostream>	// std::cout
2
3int main() {
4    std::cout << "Hello world!" << std::endl;
5    return EXIT_SUCCESS;
6}

Mathe-Formeln

Siehe Myst-Doku

Mit :::{math}...::: für Block-Formeln

(1)\[ \begin{align}\begin{aligned}(a + b)^2 = a^2 + 2ab + b^2\\\begin{split}(a + b)^2 &= (a + b)(a + b) \\ &= a^2 + 2ab + b^2\end{split}\end{aligned}\end{align} \]

\(\LaTeX\)-Mathe-Formeln

Siehe Myst-Doku

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.

(2)\[\begin{split} y & = ax^2 + bx + c \\ f(x) & = x^2 + 2xy + y^2 \end{split}\]

Mit \begin...\end für Block-Formeln

Siehe Myst-Doku

\[\begin{gather*} a_1=b_1+c_1\\ a_2=b_2+c_2-d_2+e_2 \end{gather*}\]
(3)\[\begin{align} a_{11}& =b_{11}& a_{12}& =b_{12}\\ a_{21}& =b_{21}& a_{22}& =b_{22}+c_{22} \end{align}\]

Bilder

Alternativtext1

Alternativtext2
Alternativtext3

This is a caption in Markdown

Alternativtext4

This is a caption in Markdown

Weitere Steuerelemente mit sphinx_design: Cards, Badges, Buttons, Drobdowns, Grid, Icons und Tabs

Siehe sphinx-design

TODO

Diagramme mit Mermaid.js

Siehe Mermaid.js-Tutorials

        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
    
        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 und Ablog-Doku

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 <h1> für den Blog-Artikel

Das kann in JupyterLab erstellt worden sein und nicht erst hinterher mit dem Editor.

{
 "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.

  {
   "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 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 und Read-The-Docs-Doku

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.

Ein-/Ausgabe für stdin, stdout, stderr ist unterdrückbar. Der nachfolgende Code wird dadurch gar nicht angezeigt, sondern nur das Ergebnis.

LaTeX-Formeln sind in Jupyter-Notebooks möglich.

Widgets können zwar gerendert werden, ahebn aber keine Funktion in Sphinx/Ablog.

Charts mit Matplotlib sind auch möglich, nur leider nicht interaktiv.

Fußnoten

Siehe Myst-Doku

  • This is a manually-numbered footnote reference.[3]

  • This is an auto-numbered footnote reference.[1]

Fin