Markdown Syntax¶

Die Generelle Syntax ist z.B. hier beschrieben: https://www.markdownguide.org/basic-syntax/.

Im Folgenden sind einige Besonderheiten von MkDocs aufgeführt.

Bilder und Anhänge¶

Beim Verwenden vom "Azure DevOps Wiki" werden Bilder und Anhänge im Ordner /docs/.attachments/ abgelegt und automatisch absolut referenziert. Das funktioniert im Azure DevOps Wiki und auf der finalen Website, jedoch nicht nativ im Repository. Damit sie überall funktionieren, muss der absolute Pfad durch den relativen ersetzt werden (für diese Seite z.B. ../.attachments/beispiel.png.)

Bilder können linksbündig oder rechtsbündig dargestellt werden { align=left }. Außerdem können sie in ihrer Größe limitiert werden { width="200" }.

Für weitere Informationen siehe mkdocs-material / images.

Soll exakt gesteuert werden, welche Inhalte nebeneinander dargestellt werden, kann man ein generisches Grid verwenden.

Beispiel:

Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.

Syntax:

![Beispiel-Bild](../.attachments/dummy-image.jpg){ align=left width="200" }

Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.

Listen und Aufzählungen¶

Viele Tools erlauben Markdown-Listen mit einer Einrückung von 2 Leerzeichen. Der Markdown Standard spezifiziert jedoch 4 Leerzeichen oder 1 Tabstopp je Ebene. MkDocs hält sich strikt an den Standard.

Beispiel:

Mit zwei Leerzeichen wird
nicht eingerückt.
Mit vier wird
- eingerückt.

Syntax:

- Mit zwei Leerzeichen wird
  - nicht eingerückt.
- Mit vier wird
    - eingerückt.

Infobox¶

Beispiel:

Info

Das ist eine Info-Box.

Syntax:

!!! info
    Das ist eine Info-Box.

Statt info können andere Symbole wie warning oder danger verwendet werden. Siehe mkdocs-material / admonitions

Collapsible Section¶

Beispiel:

Beschreibung des eingeklappten Bereichs

Inhalt des eingeklappten Bereichs.

Syntax:

<details>
<summary>Beschreibung des eingeklappten Bereichs</summary>

Inhalt des eingeklappten Bereichs.

</details>

Emojis & Icons¶

Unter mkdocs-material / icons / search können alle verfügbaren Emojis & Icons durchsucht werden.

Beispiel: >

"Gläser mit Sti(e)l sind besser", V.C. 2024

Syntax: :material-glass-wine: > :fontawesome-solid-glass-water:

Mailto¶

Beispiel: Mail an John

Syntax: [Mail an John :fontawesome-regular-envelope:](mailto:t.doe@test.com)

Hervorheben¶

Beispiel: hervorgehoben

Syntax: ==hervorgehoben==

Fußnoten¶

Fußnoten können im gesamten Dokument beschrieben werden, aber werden immer am Ende der Seite angezeigt.

Beispiel:

Bitte das Kleingedruckte¹ beachten.

Syntax:

Bitte das Kleingedruckte[^1] beachten.
[^1]: Hier steht das Kleingedruckte

Tags¶

Am Anfang einer Markdown-Seite können beliebig viele Tags aufgenommen werden. Dies werden zu Beginn der Seite angezeigt und unter den zentralen Tags aufgeführt.

Beispiel: siehe oben.

Syntax:

---
tags:
  - beispiel
---

Grid¶

Grid Cards¶

Zum darstellen von einfachen Karten mit Symbolen und Texten. Für weitere Beispiele, z.B. mit komplexeren Inhalten siehe mkdocs-material / grids

Beispiel:

HTML for content and structure
JavaScript for interactivity
CSS for text running out of boxes
Internet Explorer ... huh?

Syntax:

<div class="grid cards" markdown>

- :fontawesome-brands-html5: __HTML__ for content and structure
- :fontawesome-brands-js: __JavaScript__ for interactivity
- :fontawesome-brands-css3: __CSS__ for text running out of boxes
- :fontawesome-brands-internet-explorer: __Internet Explorer__ ... huh?

</div>

Generic Grid¶

Zum gruppieren jeglicher Inhalte in einem Grid bzw. nebeneinander.

Beispiel:

Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.

Syntax:

<div class="grid" markdown>
<div markdown>
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.
</div>
<div markdown>
![Beispiel-Bild](../.attachments/dummy-image.jpg){ width="200" }
</div>
</div>

Tabs¶

Tabs erlauben es, Inhalte in verschiedenen Reitern darzustellen. Siehe mkdocs-material / content-tabs

Beispiel:

Unordered listOrdered list

Sed sagittis eleifend rutrum
Donec vitae suscipit est
Nulla tempor lobortis orci

Sed sagittis eleifend rutrum
Donec vitae suscipit est
Nulla tempor lobortis orci

Syntax:

=== "Unordered list"

    - Sed sagittis eleifend rutrum
    - Donec vitae suscipit est
    - Nulla tempor lobortis orci

=== "Ordered list"

    1. Sed sagittis eleifend rutrum
    2. Donec vitae suscipit est
    3. Nulla tempor lobortis orci

Hier steht das Kleingedruckte ↩