Zum Inhalt

MkDocs

Das ist eine Kurzbeschreibung wie MkDocs auf dieser Homepage verwendet wird

Installation

cmd
1
pip install mkdocs-material

Willkommen zu MkDocs

Die ganze Dokumentation befindet sich unter mkdocs.org.

MkDocs Befehle

  • mkdocs new [dir-name] - Erstellt ein neues Projekt.
  • mkdocs serve - Startet den live-reloding Dokumenten Server.
  • mkdocs build - Erstellt die Dokumentations-Seite.
  • mkdocs -h - Zeigt die Hilfe zu den Befehlen.

Project layout

1
2
3
4
mkdocs.yml    # Konfiguration Datei.
docs/
    index.md  # Dokumentation Homepage.
    ...       # Andere Markdown Seiten, Bilder und andere Dateien.

globale Einstellungen

Einstellungen werden im Root-Ordner in der Datei mkdocs.yml gemacht.

Datei-URL's statt Ordner-URL's

mkdocs.yml
1
use_directory_urls: false
Mit dieser Einstellung werden Die dateien direkt mit .html-Endung angesprochen,
und nicht als Ordner.
Damit wird die Struktur 1:1 so abgebildet wie die Struktur der Markdown-Dateien erstellt worden ist.

Theme material

Installation

cmd
1
pip install mkdocs-material

Material Homepage

squidfunk.github.io/mkdocs-material

Aktivieren/ Konfigurieren

mkdocs.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
theme: 
  name: material 
  language: de
  palette: 
    primary: blue grey  
    - scheme: default
      toggle:
        icon: material/toggle-switch-off-outline 
        name: Switch to dark mode
    - scheme: slate 
      toggle:
        icon: material/toggle-switch
        name: Switch to light mode
Diese Einstellung verwendet das Layout material,
und es kann zwischen einem "normalen" und "dunklen" Modus umgeschalten werden.

Code Syntax Hervorhebung

mkdocs.yml
1
2
3
4
5
6
markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences  # Für Tabs zum Wechseln

Diese Erweiterung verbessert das Anzeigen von Code-Blöcken.
Damit lassen sich Titel und Zeilennummer im Code-Block anzeigen.

1
2
3
4
5
``` gd title="meineDatei.gd" linenums="1"
var x = 1

func _ready():
    pass
erstellt
meineDatei.gd
1
2
3
4
5
6
7
8
var x = 1

# wird ausgeführt wenn fertig geladen
func _ready():
    pass

func _progress(delta) -> void:
  pass

Blog Beitrag

Bei einem Blog Beitrag soll folgender Header im MarkDown eingegeben werden

Blog Header
1
2
3
4
5
---
title: Neue Homepage
description: Eine neue Homepage basierend auf mkDocs
date: "2021-03-21 00:00:00"
---

Eigene CSS-Styles

mkdocs.yml
1
2
3
4
5
extra_css:
  - css/meincss.css

markdown_extensions:
  - attr_list

Mit dieser Einsellung können eigene Styles eingebunden,
und verwendet werden.

Um zum Beispiel die Style-Klasse "green" einem Absatz hinzuzufügen:

mein_dokument.md
1
2
Das ist mein Text in grün.
{ .green }

Das ist mein Text in grün.

Das ist Links
mit 2 Zeilen

Und der Rest

Tabs zum wechseln

mkdocs.jml
1
2
3
markdown_extensions:
  - pymdownx.tabbed:
      alternate_style: true

Damit können Tabs für Code, und auch andere Inhalte erstellt werden.

meine_datei.md
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
=== "C"

    ``` c title="meine_datei.c"
    #include <stdio.h>

    int main(void) {
      printf("Hello world!\n");
      return 0;
    }
    ```

=== "C++"

    ``` c++ title="meine_datei.c"
    #include <iostream>

    int main(void) {
      std::cout << "Hello world!" << std::endl;
      return 0;
    }
    ```
erstellt

meine_datei.c
1
2
3
4
5
6
#include <stdio.h>

int main(void) {
  printf("Hello world!\n");
  return 0;
}
meine_datei.c
1
2
3
4
5
6
#include <iostream>

int main(void) {
  std::cout << "Hello world!" << std::endl;
  return 0;
}

Info-Blöcke

mkdocs.yml
1
2
3
4
markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences

Estellt hervorgehobene Blöcke

meine_datei.md
1
2
3
!!! note "Titel"
    Dier Block muss Eingerückt sein
    um richtig angezeigt zu werden

Tipp: Titel anzeigen/ verbergen

Und es kann auch ein Titel angegeben werden.
Soll kein Titel angezeigt werden, wird ein "" Leerstring angegeben.

Folgende Blöcke(Bezeichner) sind möglich.

  • note
  • abstact
  • info
  • tip
  • success
  • question
  • warning
  • failure
  • danger
  • bug
  • example
  • quote

Note

Das ist ein Hinweis

Warning

Das ist eine Warnung

Failure

Das ist ein Fehler

Success

Das ist OK

Question

Das ist eine Frage

Info

Das ist eine Info

Tip

Das ist ein Tip

Text hervorheben, markieren

mkdocs.yml
1
2
3
4
5
6
markdown_extensions:
  - pymdownx.critic
  - pymdownx.caret
  - pymdownx.keys
  - pymdownx.mark
  - pymdownx.tilde

Mit diesen Erweiterungen kann ein Text einfacher Markiert und hervorgehoben werden.

meine_datei.md
1
2
3
{ ==
Dieser Absatz wird hervorgehoben
==}
erstellt

Dieser Absatz wird hervorgehoben

Tastatur Codes

meine_datei.md
1
++ctrl+alt+del++
erstellt

Ctrl+Alt+Del

Meta

mkdocs.yml
1
2
markdown_extensions:
  - meta

Im Header angegeben, wird das Menü in diesem Dokument versteckt.

mein_dokument.md
1
2
3
4
5
---
hide:
    - navigation
    - toc
---

Zurück zum Seitenanfang