Zum Inhalt

Setup

Infos zu mkdocs

Installation

Setup mit Docker von mkdocs-material

Terminal
docker pull squidfunk/mkdocs-material

Setup von Andreas

(noch docker-compose.yml anpassen)

repo clonen [oder zip entpacken]

docker-compose.yml --livereload einfügen siehe unten

[ist im Repo angepasst worden]

Und schon kann’s losgehen…

Terminal
git clone https://gitlab.thermaldrones.de/thermaldrones/dokumentation.git
cd projektverzeichnis
docker compose up

Hinweis

Anstatt von Docker Desktop besser OrbStack unter MacOS nutzen

OrbStack Website

Build

Backup machen - dann

docker build testen

Building your site

When you’re finished editing, you can build a static site from your Markdown files with:

mkdocs build

If you’re running Material for MkDocs from within Docker, use:

docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material build

docker run --rm -it -v "%cd%":/docs squidfunk/mkdocs-material build

script für build && rsync

#!/bin/sh
USER=username
HOST=hostname
DIR=/path/to/mkdocs   # the directory where your web site files should go

docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material build && rsync -avz --exclude='.DS_Store' site/ ${USER}@${HOST}:~/${DIR} 

# rsync ohne --delete !
# rsync dry run -n !

dauert nur ca. 5-10 sec 👍

Git Workflow

Änderungen in Git dokumentieren:

git status - git add - git commit -m "Beschreibung" - git push

Terminal
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
❯ git status
On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   docs/team/copy-paste.md

no changes added to commit (use "git add" and/or "git commit -a")
❯ git add docs/team/copy-paste.md
❯ git status
On branch main
Your branch is up to date with 'origin/main'.

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   docs/team/copy-paste.md

git commit -m "Titel bei Bild hinzugefügt"            
main 5df8405] Titel bei Bild hinzugefügt
 1 file changed, 1 insertion(+), 1 deletion(-)
❯ git status
On branch main
Your branch is ahead of 'origin/main' by 1 commit.
  (use "git push" to publish your local commits)

nothing to commit, working tree clean
❯ git push
Enumerating objects: 9, done.
Counting objects: 100% (9/9), done.
Delta compression using up to 8 threads
Compressing objects: 100% (5/5), done.
Writing objects: 100% (5/5), 439 bytes | 439.00 KiB/s, done.
Total 5 (delta 4), reused 0 (delta 0), pack-reused 0
To https://gitlab.thermaldrones.de/thermaldrones/dokumentation.git
   4a359f4..5df8405  main -> main

Änderungen

docker-compose.yml

[--livereload hinzugefügt]

livereload hat vorher nicht funktioniert

services:
  mkdocs:
    image: squidfunk/mkdocs-material
    container_name: mkdocs
    restart: unless-stopped
    ports:
      - "8000:8000"
    volumes:
      - .:/docs
    environment:
      - WATCHDOG_USE_POLLING=true

    # command: serve --dev-addr 0.0.0.0:8000
    command: serve `--livereload` --dev-addr 0.0.0.0:8000 --watch docs --watch mkdocs.yml
#     networks:
#       - proxy_net

# networks:
#   proxy_net:
#     external: true
#     name: wordpress_proxy

Bug ist bekannt - mkdocs does not watch for file changes when using click>8.2.1 #4032

Lösung:

mkdocs serve doesn’t reload upon change anymore #8478

mkdocs.yml

Konfiguration von mkdocs - Ausgangszustand

mkdocs.yml
site_name: Dokumentation
site_description: Dokumentationen zu POIApp, POICloud und POIStudio
site_author: thermal DRONES

theme:
  name: material
  language: de
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.top
    - search.highlight
    - search.share
    - search.suggest
  logo: assets/images/logo.png
  favicon: assets/images/favicon.png
  font:
    text: Catamaran
    code: Roboto Mono
  palette:
    # Heller Modus
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: white
      accent: deep orange
      toggle:
        icon: material/brightness-7
        name: Wechsel zum Dark Mode
    # Dunkler Modus
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: deep orange
      accent: deep orange
      toggle:
        icon: material/brightness-4
        name: Wechsel zum Light Mode

# Custom CSS
extra_css:
  - stylesheets/extra.css

# Navigation
nav:
  - POIApp: poiapp.md
  - POICloud: poicloud.md
  - POIConnect: poiconnect.md
  - POIStudio: poistudio.md    

# Erweiterungen für Markdown
markdown_extensions:
  - admonition
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - smarty  # Konvertiert "Zitate", -- (Gedankenstriche) und ... (Auslassungspunkte)
  - pymdownx.smartsymbols  # Konvertiert (c), (tm), +/- etc. in echte Symbole

Automatic light / dark mode

mkdocs.yml
theme:
  palette:

    # Palette toggle for automatic mode
    - media: "(prefers-color-scheme)"
      toggle:
        icon: material/brightness-auto
        name: Switch to light mode

    # Palette toggle for light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default 
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode

    # Palette toggle for dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle:
        icon: material/brightness-4
        name: Switch to system preference

Material for MkDocs will now change the color palette each time the
operating system switches between light and dark appearance, even when the user doesn’t reload the site.

Info zum automatischen light/dark mode

navigation.sections (war bereits aktiviert)

When sections are enabled, top-level sections are rendered as groups in the sidebar for viewports above 1220px, but remain as-is on mobile. Add the following lines to mkdocs.yml:

mkdocs.yml
theme:
  features:
    - navigation.sections

im Moment deaktiviert:

mkdocs.yml
theme:
  features:
    # - navigation.sections

navigation.footer hinzugefügt

mkdocs.yml
theme:
  features:
    - navigation.footer

navigation.indexes hinzugefügt

When section index pages are enabled, documents can be directly attached to sections, which is particularly useful for providing overview pages. Add the following lines to mkdocs.yml:

mkdocs.yml
theme:
  features:
    - navigation.indexes

In order to link a page to a section, create a new document with the name index.md in the respective folder, and add it to the beginning of your navigation section:

mkdocs.yml
nav:
  - Section:
    - section/index.md 
    - Page 1: section/page-1.md
    ...
    - Page n: section/page-n.md

Infos zum Navigations-Setup

markdown_extensions

mkdocs.yml
markdown_extensions:
  - attr_list
  - md_in_html

- attr_list ermöglicht HTML in Markdown

- md_in_html ermöglicht z.B. Markdown im <div>

Infos zu - attr_list

Infos zu - md_in_html

mkdocs.yml
markdown_extensions:
  - toc:
      permalink: true

Info zu permalinks - auch mit Angabe von Link anstatt true möglich

mkdocs.yml
markdown_extensions:
  - pymdownx.details

- pymdownx.details ermöglicht “ausklappbare” Admonitions (Hinweisboxen)

Infos zu - pymdownx.details

mkdocs.yml
markdown_extensions:
  - pymdownx.tabbed:
      alternate_style: true
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower

slugify für links zu content tabs

Infos zu mkdocs-material content tabs

mkdocs.yml
theme:
  features:
    - content.code.copy

- content.code.copy erzeugt copyButton bei Code Blocks

Info zu mkdocs-material code blocks

mkdocs.yml
markdown_extensions:
  - pymdownx.critic
  - pymdownx.caret
  - pymdownx.keys
  - pymdownx.mark
  - pymdownx.tilde

extensions für diverse Markierungsmöglichkeiten

Info zu mkdocs-material formatting

mkdocs.yml
markdown_extensions:
  - pymdownx.blocks.caption
extension für captions (im Markdown Block)

Info zu mkdocs-material captions

mkdocs.yml
markdown_extensions:
- pymdownx.tasklist:
      custom_checkbox: true

extension für Tasklists

Info zu mkdocs-material tasklists

mkdocs.yml
markdown_extensions:
  - footnotes

extension für Footnotes

mkdocs.yml
theme:
  features:
    - content.footnote.tooltips

Tooltips für Footnotes

Info zu mkdocs-material footnotes

mkdocs.yml
markdown_extensions:
  - def_list

extension für Definition Lists

Info zu mkdocs-material definition lists

mkdocs.yml
markdown_extensions:
  - abbr

extension für abbreviations

Info zu mkdocs-material abbreviations

mkdocs.yml
markdown_extensions:
  - pymdownx.blocks.html

extension für block.html

Native two column layout #6845

Info zu mkdocs-material block.html

mkdocs.yml
markdown_extensions:
  - pymdownx.magiclink

extension für magiclink

Info zu magiclink

mkdocs.yml
extra:
  social:
    - icon: fontawesome/solid/paper-plane
      link: mailto:<info@thermaldrones.de>
    - icon: material/youtube
      link: https://www.youtube.com/channel/UCpHeWXgoEYdRXdZXhH7FVmA
    - icon: fontawesome/brands/instagram
      link: https://instagram.com/thermaldrones
    - icon: fontawesome/brands/facebook
      link: https://www.facebook.com/profile.php?id=100067918641864
    - icon: fontawesome/brands/linkedin
      link: https://www.linkedin.com/company/thermaldrones/?originalSubdomain=de

Info zu mkdocs-material social links im footer

Dark Mode

dark mode funktioniert nicht - Header H1-H4 nicht sichtbar

Desktop-light-alt

Desktop-dark-alt

iPhone-light-alt

iPhone-dark-alt

jetzt die angepasste Version:

.md-typeset h1-h4 wurde zu [data-md-color-scheme="default"] .md-typeset h1-h4

.md-typeset h1-h4 auf font-weight: 700;und color: #222222;

bleibt wie geplant (Schrift bei Header H1-H4 kräftiger)

header color komplett orange und logo wieder in original Grösse

Desktop-light-neu

Desktop-dark-neu

iPhone-light-neu

iPhone-dark-neu

extra.css

Zeile 41-59 auskommentiert - funktioniert nicht im dark mode

extra.css
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
:root {
  /* Brand Colors from thermaldrones.de */
  --md-primary-fg-color: #f26522;
  --md-primary-fg-color--light: #f5844e;
  --md-primary-fg-color--dark: #b84a16;

  /* Corner Roundness */
  --md-border-radius: 6px;
}

/* Hintergrund für Header und Tabs im hellen Modus auf Weiß setzen */
[data-md-color-scheme="default"] .md-header {
  background-color: #ffffff;
  color: #333333;
  /* Dunkle Textfarbe für Lesbarkeit */
}

[data-md-color-scheme="default"] .md-tabs {
  background-color: #ffffff;
  border-bottom: 1px solid #eeeeee;
  /* Leichte Trennlinie */
}

/* Icons und Logo-Farbe anpassen, damit sie auf Weiß sichtbar sind */
[data-md-color-scheme="default"] .md-header__button,
[data-md-color-scheme="default"] .md-header__title {
  color: #333333;
}

/* Farbe der Tabs (Navigation unter dem Header) */
[data-md-color-scheme="default"] .md-tabs__link {
  color: #555555;
}

/* Aktiver Tab-Link */
[data-md-color-scheme="default"] .md-tabs__item--active .md-tabs__link {
  color: #ef5350;
  /* Hier wird deine Akzentfarbe 'deep orange' genutzt */
}

/* Apply Brand Styling - auskommentiert - funktioniert nicht richtig, 
da die Farben für den dunklen Modus zu dunkel sind 
.md-typeset h1,
.md-typeset h2,
.md-typeset h3,
.md-typeset h4 {
  font-weight: 700;
  color: #222222;
}

.md-header {
  background-color: #222222;
}

.md-header__button.md-logo img {
  height: 2rem;
  width: auto;
}
*/

/* Card and Button Rounding */
.md-card,
.md-button,
.md-nav__link {
  border-radius: var(--md-border-radius);
}

/* Adjusting the search bar for the dark header */
.md-search__input {
  border-radius: var(--md-border-radius);
}

.md-typeset .admonition,
.md-typeset details {
  border-radius: .5rem;
}

extra.css [NEU]

jetzt die angepasste Version:

.md-typeset h1-h4 wurde zu [data-md-color-scheme="default"] .md-typeset h1-h4

.md-typeset h1-h4 auf font-weight: 700;und color: #222222;

bleibt wie geplant (Schrift bei Header H1-H4 kräftiger)

header color komplett orange und logo wieder in original Grösse

extra.css
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
/* Apply Brand Styling - auskommentiert - funktioniert nicht richtig, 
da die Farben für den dunklen Modus zu dunkel sind */
[data-md-color-scheme="default"] .md-typeset h1,
[data-md-color-scheme="default"] .md-typeset h2,
[data-md-color-scheme="default"] .md-typeset h3,
[data-md-color-scheme="default"] .md-typeset h4 {
  font-weight: 700;
  color: #222222;
}
/*
  .md-header {
  background-color: #222222;
}

 .md-header__button.md-logo img {
  height: 2rem;
  width: auto;
}
*/

Video Einbindung

responsiv mit CSS-Wrapper-Element

extra.css
.video-container {
    position: relative;
    padding-bottom: 56.25%; /* 16:9 Seitenverhältnis */
    height: 0;
    overflow: hidden;
    max-width: 100%;
}

.video-container iframe {
    position: absolute;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
}

Video im Content einbinden:

Beispiel für Youtube Video

teilen - einbetten - Optionen zum Einbetten:

Player-Steuerelemente anzeigen.

Erweiterten Datenschutzmodus aktivieren.

copy & paste

iframe Block mit <div class="video-container"> einschliessen

content.md
<div class="video-container">
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/videoseries?si=HdJWp2y2GtN9dDKr&amp;list=PLnsAdFrlG7q9YKwoZasuHe9-xKG8Lw7FV" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
</div>