bernd/webseiten-mit-mkdocs
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
Files
c035f7c85af8952200517956c58e81b52365417c
webseiten-mit-mkdocs/docs/index.md
T
Bernd Reuther 240f7f7727 änderungen
2020-10-22 09:57:53 +02:00

7.7 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

js-sequence-diagrams

pip3 install git+https://github.com/fcannizzaro/mkdocs-sequence-js-plugin

in "mkdocs.yml":

plugins:
  - sequence-js:
      theme: simple|hand      # diagram style
      popup: true             # enable "click to zoom" diagram

Beispiele:

    ```sequence
    Title: Das ist der Titel
    A->B: normale Linie
    B-->C: unterbrochene Linie
    C->>D: offener Pfeil
    D-->>A: unterbrochener offener Pfeil
    ```

Title: Here is a title
A->B: normale Linie
B-->C: unterbrochene Linie
C->>D: offener Pfeil
D-->>A: unterbrochener offener Pfeil

    ```sequence
    Note left of A: Note to the\n left of A
    Note right of A: Note to the\n right of A
    Note over A: Note over A
    Note over A,B: Note over both A and B
    ```

Note left of A: Note to the\n left of A
Note right of A: Note to the\n right of A
Note over A: Note over A
Note over A,B: Note over both A and B

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
Reference in New Issue View Git Blame Copy Permalink