webseiten-mit-mkdocs/docs/index.md at a64c62d297bbe51a4d9093ddfb2a4994db5929e7

bernd/webseiten-mit-mkdocs

Fork 0

Files

T

Bernd Reuther 167b8387a9 Änderungsdatum

2020-10-23 15:02:18 +02:00

7.2 KiB

Raw Blame History

Ausgangspunkt

Ubuntu 18.04 Server
Python3 und Pip3

apt install python3 python3-pip

mkdocs installieren

pip3 install mkdocs

Arbeitsverzeichnis anlegen

mkdir /opt/mkdocs
cd /opt/mkdocs

neue Vorlage anlegen

mkdocs new meine-doku

Seite testen (über internen Server)

Standardmäßig hört der interne Server nur auf "localhos". Wenn man die Seite von einem anderen Rechner aus testen will, muss man mit dem Parameter "-a 0.0.0.0:8000" starten

mkdocs serve -a 0.0.0.0:8000

statische Seite erzeugen (mit Parameter -d wird das Zielverzeichnis übergeben)

mkdocs build -d /var/www/html/meine-doku

Material-Theme für mkdocs

pip3 install mkdocs-material

Datei mkdocs.yml anpassen

theme:
  name: material
  language: de
  favicon: ../icon.png
  logo: ../logo.png
  font: false
  custom_dir: overrides

Layout anpassen

=== "/opt/mkdocs/meine-doku/overrides/partials/footer.html" ... <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class="md-footer-copyright"> {% if config.copyright %} <div class="md-footer-copyright__highlight"> {{ config.copyright }} </div> {% endif %} Made with <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener"> Material for MkDocs </a> /. <a href="/impressum.html" target="_blank" rel="noopener"> Impressum </a> /. <a href="/datenschutz.html" target="_blank" rel="noopener"> Datenschutzerklärung </a> </div> {% include "partials/social.html" %} </div> </div> ...

Logo und Icon über Apache umleiten

=== "/etc/apache2/conf-available/custom.conf" ``` # Jugend- und Gemeindezntrum ENERGIE # Evangelisch-Freikirchliche Gemeinde Bad Lausick # Anpassungen für alle Webseiten # Impressum / Datenschutzerklärung

Alias "/impressum.html" "/var/www/html/impressum.html"
Alias "/datenschutz.html" "/var/www/html/datenschutz.html"
Alias "/logo.png" "/var/www/html/logo.svg"
Alias "/icon.ico" "/var/www/html/logo.svg"

<Location /impressum.html>
    RewriteEngine off
    ProxyPass !
</Location>

<Location /datenschutz.html>
    RewriteEngine off
    ProxyPass !
</Location>

<Location /logo.png>
    RewriteEngine off
    ProxyPass !
</Location>

<Location /icon.ico>
    RewriteEngine off
    ProxyPass !
</Location>
```

Die Deaktivierung von "Rewrite" und "ProxyPass" ist nur bei entsprechend verwendeten Modulen notwendig

Konfiguration aktivieren

a2enconf custom.conf
systemctl reload apache2

Markdown-Erweiterungen aktivieren

Die Erweiterungen werden in der Datei mkdocs.yml aktiviert

Abkürzungen

markdown_extensions:
  - abbr

Abkürzungen können an irgendeiner Stelle im Dokument definiert werden nach dem Prinzip:

*[EFG]: Evangelisch-Freikirchliche Gemeinde

...und können dann im laufenden Text verwendet werden. z.B.: EFG Bad Lausick

*[EFG]: Evangelisch-Freikirchliche Gemeinde

Hinweise

markdown_extensions:
  - admonition

Nutzbare Typen: "attention", "caution", "danger", "error", "bug", "example", "note", "abstract", "info", "hint", "check", "faq", "quote"

!!! attention Achtung
    Achtung!

!!! attention Achtung Achtung!

!!! caution Vorsicht!

!!! danger Gefahr!

!!! error Fehler!

!!! bug Fehler!

!!! example Beispiel.

!!! note Notiz!

!!! abstract Zusammenfassung.

!!! info Information.

!!! hint Hinweis!

!!! check Fertig!

!!! faq Frage?

!!! quote Zitat

Details

(leider keine Vorschau in VS Code)

markdown_extensions:
  - pymdownx.details

??? css-klasse "Überschrift" Hier kommt der Inhalt rein.

???+ note "geöffnet"

??? danger "eingebettete Details!"
    Noch mehr Inhalt.

Quellcode einbinden

markdown_extensions:
  - pymdownx.highlight
  - pymdownx.superfences
  - pymdownx.inlinehilite
  - pymdownx.keys

    ``` python linenums="1"
    def bubble_sort(items):
        for i in range(len(items)):
            for j in range(len(items) - 1 - i):
                if items[j] > items[j + 1]:
                    items[j], items[j + 1] = items[j + 1], items[j]
    ```

def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

    ``` python hl_lines="2 3"
    def bubble_sort(items):
        for i in range(len(items)):
            for j in range(len(items) - 1 - i):
                if items[j] > items[j + 1]:
                    items[j], items[j + 1] = items[j + 1], items[j]
    ```

def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

    ++ctrl+alt+del++

++ctrl+alt+del++

Registerkarten

markdown_extensions:
  - pymdownx.tabbed

    === "nicht nummerierte Liste"

        * punkt 1
        * punkt 2
        * punkt 3

    === "nummerierte Liste"

        1. punkt 1
        2. punkt 2
        3. punkt 3

=== "nicht nummerierte Liste"

* punkt 1
* punkt 2
* punkt 3

=== "nummerierte Liste"

1. punkt 1
2. punkt 2
3. punkt 3

Plugins

Benutzerdefinierte Variablen

pip3 install mkdocs-user-defined-values

in "mkdocs.yml":

plugins:
  - user-defined-values:
      keywords:
        IP_ADRESSE:
          placeholder: z.B. 0.0.0.0
        DOMAIN_NAME:
          placeholder: z.B. fritz.box

Eingabeformular einbinden:

{{{user-defined-values}}}

Die IP-Adresse ist: $IP_ADRESSE, der Domain-Name: $DOMAIN_NAME

# das sollte auch in Code-Blöcken funktionieren
    <Location "/">

        RewriteEngine on
        RewriteCond %{HTTP:UPGRADE} ^WebSocket$ [NC]
        RewriteCond %{HTTP:CONNECTION} Upgrade$ [NC]
        RewriteRule .* ws://$IP_ADRESSE:8080%{REQUEST_URI} [P]

        ProxyPass http://$IP_ADRESSE:8080/
        ProxyPassReverse http://$IP_ADRESSE:8080/
        ProxyHTMLURLMap http://$IP_ADRESSE:8080 /

    </Location>

PDF Ausgabe

sudo apt-get install build-essential python3-dev python3-pip python3-setuptools python3-wheel python3-cffi libcairo2 libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf2.0-0 libffi-dev shared-mime-info

pip3 install WeasyPrint
pip3 install mkdocs-with-pdf

Änderung in "mkdocs.yml":

plugins:
  - with-pdf

Block-Diagramme

pip3 install mkdocs-mermaid2-plugin