Spezielle Elemente in MkDocs-Material

Das Material-Theme ist eines der beliebtesten Themes für MkDocs und bringt einige Erweiterungen für die visuell ansprechene Gestaltung eurer Dokumentation mit. Eine vollständige Übersicht inklusive Codebeispielen findet sich hier, einige Highlights haben wir auf dieser Seite eingebaut.

Admonitions

Admonitions, auch Call-Outs genannt, sind eine gute Wahl um zusätzliche Inhalte einzufügen, ohne den Dokumentfluss wesentlich zu unterbrechen. MkDocs bietet mehrere verschiedene Arten von Admonitions und ermöglicht Verschachtelung beliebiger Inhalte.

Codeblöcke

Auch Codeblöcke lassen sich sehr einfach einfügen und werden automatisch mit einem Kopieren-Button versehen. Sie werden über drei Backticks eingefasst.
Wenn zu Beginn des Codeblocks die entsprechende Codesprache angegeben wird ergänzt MkDocs farbliche passende Syntax-Highlights.

Hier beispielsweise im YAML-Format:

```yaml
site_name: CC Documentation as Code Template
copyright: Copyright © Computacenter 2022
```

Dieser Code-Block wird folgendermaßen dargestellt:

site_name: CC Documentation as Code Template
copyright: Copyright © Computacenter 2022

Einzelne Zeilen in Code-Blöcken können folgendermaßen hervorgehoben werden, Zeilen können nummeriert werden:

```py hl_lines="2 3" linenums="1"
def sort_ip(unsorted_ip_list):
    """ Sort list of IP addresses """

    if not isinstance(unsorted_ip_list, list):
        raise AnsibleFilterTypeError("Filter needs list input, got '%s'" % type(unsorted_ip_list))
    else:
        sorted_ip_list = sorted(unsorted_ip_list, key=netaddr.IPAddress)

    return sorted_ip_list
```

In MkDocs wird der Block entsprechend dargestellt:

1
2
3
4
5
6
7
8
9

def sort_ip(unsorted_ip_list):
    """ Sort list of IP addresses """

    if not isinstance(unsorted_ip_list, list):
        raise AnsibleFilterTypeError("Filter needs list input, got '%s'" % type(unsorted_ip_list))
    else:
        sorted_ip_list = sorted(unsorted_ip_list, key=netaddr.IPAddress)

    return sorted_ip_list

Tabs

Besonders praktisch für die Darstellungen von Code für verschiedene Umgebungen oder leicht abweichende Befehle eignet sich der Einsatz von Tab-Bars:

yum install python3-pip -y

sudo apt install python3-pip

pkgadd -d http://get.opencsw.org/now
/opt/csw/bin/pkgutil -U
/opt/csw/bin/pkgutil -y -i py_pip 
/usr/sbin/pkgchk -L CSWpy-pip # list files

Listen

Auch (statische!) Listen sind in den verschiedensten Formen möglich, zum Beispiel als ToDo-Liste.

• Lorem ipsum dolor sit amet, consectetur adipiscing elit
• Vestibulum convallis sit amet nisi a tincidunt
  • In hac habitasse platea dictumst
  • In scelerisque nibh non dolor mollis congue sed et metus
  • Praesent sed risus massa
• Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque

Tabellen

Alle Tabellen können in MkDocs selbstständig sortiert werden, in der Titelzeile kann durch einen Klick alphabetisch aufsteigend oder absteigend sortiert werden.

Die Tabelle wird in Markdown folgendermaßen definiert. Hier werden zusätzlich noch Symbole in der zweiten Spalte verwendet, diese werden durch zwei Doppelpunkte eingefasst:

| Method      | Description                          |
| ----------- | ------------------------------------ |
| `GET`       | :material-check:     Fetch resource  |
| `PUT`       | :material-check-all: Update resource |
| `DELETE`    | :material-close:     Delete resource |