MKDOCS Substitute

Sämtliche meiner Seiten sind werden seit einigen Jahren mit einem statischen Webseiten-Generator namens "mkdocs" ⧉ erzeugt. Dieses Tool ist sehr einfach aufgebaut und erfüllt fast alle meine Anforderungen, insbesondere, wenn man es mit dem "Material-Theme" ⧉ zusammen benutzt. Allerdings fehlen mir immer wieder mal ein paar Funktionen und irgendwann habe ich dann angefangen mich mit den Plugins dieses Tools zu beschäftigen.

MKDOCS Substitute ist mitlerweile eine mächtige Erweiterung von mkdocs / Material geworden. Wie der Name des Plugins sagt, können bestimmte Textpassagen / Platzhalter in den Markdown Quelldateien durch beliebige Textbausteine ersetzt werden. Mehr noch ... mit MKDOCS Substitute fügen Sie Elemente wie Alerts, Badges, Toast, frei verfügbare Icons, Modal-Fenster, Social Media Widgets etc. ein ohne sich im komplizierte Javascript Funktionen oder lange HTML Elemente kümmern zu müssen

INSTALLATION

Öffnen Sie die Windows Terminal-Anwendung und geben Sie diesen Befehl ein:

pip install mkdocs-substitute-plugin

Das Tool sollte problemlos installiert werden können. Beachten Sie ggf. die Mindest-Versionsanforderung von mkdocs und führen Sie ggf. ein Upgrade durch. Getestet und entwickelt wurde MKDOCS Substitute unter Python mit MKDOCS und Material

Das Plugin wird in der mkdocs.yaml wie folgt aktiviert:

plugins:
    - substitute-plugin:
        substitutions_file: substitutions.json

substitutions.json
Die substitutions.json ist zwingend notwendig. In dieser Datei werden die Ersetzungen definiert. Wie das für die einzelnen Elemente funktioniert, erklärt diese Anleitung. Für den Anfang legen Sie eine leere substitutions.json Datei mit diesem Inhalt an. Diese Datei sollte in demselben Verzeichnis liegen, wie die mkdocs.yaml (in der Regel wird dies das Root Verzeichnis ihres Projektes sein).

GRUNDLAGEN - Einfache Ersetzungen

Zunächst können Sie mit MKDOCS SUBSTITUTE beliebige Platzhalter erstellen, durch einen Text überall, auf all ihren Seiten ersetzt werden soll. Beispiel: Sie wollen auf mehreren Seiten in ihrem Projekt einen Hinweis einbauen, der die Besucher/Innen ihrer Seite darauf aufmerksam macht, dass man sie jederzeit per E-Mail kontaktieren kann. Den passenden Link, der das Standard E-Mail Programm der Besucher/Innen öffnet, wird gleich mit eingefügt. Das würde dann in der substitutions.json wie folgt aussehen:

In ihren Markdown Dateien setzen Sie dann einfach den Platzhalter ein ...

An Stelle von [ MEIN_HTML_BLOCK ] wird dann rechtsbündig in roter Schrift Hallo Welt erscheinen.

So können Sie ganze HTML Blöcke definieren und als Baustein jederzeit einfügen. Die Anwendunsgmöglichkeiten sind vielfältig

Es gibt in MKDOCS Substitute aber auch viele bereits vorgefertigte Ersetzungen. Diese sind durch den Beginn einer Phrase mit einer eckigen Klammer definiert. Diese Elemente werden nun vorgestellt:

Icons von PICTOGRAMMERS

Fontawesome ⧉ kennt vermutlich jeder - ein Webfont, der tausende von Symbolen beinhaltet, die man vielfältig auf der eigenen Seite nutzen kann. Allerdings ist die Anzahl der frei verfügbaren Icons beschränkt. Pictogrammers bieten hier eine freie Alternative an. Dort stehen mehr als 7.000 Icons zur Verfügung.

Dazu muss die CSS Datei der Webfonts von PICTOGRAMMERS in die mkdocs.yaml Datei eingefügt werden:

extra_css:
    - https://cdn.jsdelivr.net/npm/@mdi/font@7.4.47/css/materialdesignicons.min.css

Icons von dort kann man mit MKDOCS Substitute sehr einfach einbetten

So definieren Sie ein ICON in ihrer substitutions.json:

"[icon_beispiel]": "account-convert",

Die Bezeichnung account-convert stammt von der Übersicht der verfügbaren Icons, die sie hier finden:

https://pictogrammers.com/library/mdi/ ⧉

Diese Icons können Sie auch in einen HTML Tag einbetten, so dass diese ICONS z.B. eine andere Größe annehmen.

ICON größer darstellen: <div style="font-size: 40px">[icon_beispiel]</div>

würde dann zu dieser Darstellung führen:

WEBSEITEN ELEMENTE

Mich hat immer gestört, dass man Elemente aus Frameworks wie Bootstrap, Foundations oder ähnlichem in MKDOCS mit dem Material Design nicht einfach so einfügen kann. Das liegt daran, dass sie sich die CSS Klassen bei der Namensgebung überschneiden. Es gibt z.B. sowohl im Bootstrap Framework, als auch im Material Theme eine CSS-Klasse namen ".container" - eine Vermengung beider Frameworks würde daher zum Chaos führen.

Ich habe daher einige dieser Elemente "nachgebaut" und diese können mit speziellen PLatzhaltern in ihre Seite ganz einfach eingebaut werden.

Alerts

TRIGGER

"[alert_*]"

Die Bootstrap Alerts sind so ähnlich wie die Admonitions in MKDOCS, allerdings ohne größeren Inhalt. Sie dienen zur Darstellung kurzer, prägnanter Hinweise und können auch aus der Seite wieder gelöscht werden ("dismissible").

So definieren Sie einen Alert in ihrer substitutions.json:

"[alert_5]": {
    "color" : "success",
    "dismissible" : "true",
    "text" : "Das ist der Alert Text, der im Alert erscheint"
},

Die Ersetzung besteht aus drei Elementen:

Parameterübersicht ALERTS:

Option	Description	Possible Values
color	Color of the alert background	"success", "alert", "warning", "info" or HEX-Value
text	Text of the Alert	Text (can include html)
dismissible	Alert can be closed on page	"true" or "false"

Als Farben dienen hierfür - da sich dieses Element bei den Einstellungen von BOOTSTRAP folgende Parameter:

Toast

TRIGGER

"[toast_*]"

TOASTs sind den Alerts sehr ähnlich. Allerdings verfügen sie über eine Titelzeile und einen Content Bereich. TOASTs eignen sich also sehr gut zum Abgrenzen und Fokussieren von Inhalten.

So sieht ein einfacher TOAST aus :

So definieren Sie einen TOAST in ihrer substitions.json Datei:

"[toast_5]": {
    "title_text" : "This is the TITLE of the Toast",
    "content" : "This is the Content of the Toast",
    "background_color" : "beige",
    "dismissible" : "true"
},

Dies sind die Optionen, die zur Gestaltung eines TOASTs zur Veefügung stehen:

Parameterübersicht TOAST:

Option	Description	Possible Values
background_color	Color of the alert background	"success", "alert", "warning", "info" or HEX-Value or HTML valid Color-Name
title_text	Title of the TOAST	Text (can include html)
content	Text of the Alert	Text (can include html)
dismissible	Alert can be closed on page	"true" or "false"

Badges

TRIGGER

"[badge_*]"

Badges sind kleine Mini-Buttons, die sich in einen laufenden Text einbinden lassen. Warnhinweise oder spezielle EyeCatcher sind die einfachen Anwendungsfälle. Die Konfiguration in der substitions.json Datei ist sehr einfach:

"[badge_5]": {
    "background-color" : "blue",
    "text-color" : "white",
    "text" : "Hervorhebung"
},

Parameterübersicht BADGES:

Option	Description	Possible Values
background-color	Background-Color of the badge	"success", "alert", "warning", "info" or HEX-Value
text-color	Text-Color of the badge	HTML Valid Colorname or HEX Value
text	Text of the Badge	Plain Text (should not include HTML)

Dieser Text in ihrer Quelldatei ...

führt dann zu diesem Output.

Einfaches Beispiel: Manchmal macht es Sinn, etwas mit einer Hervorhebung zu präsentieren ...

Sticky Notes

TRIGGER

"[note_*]"

STICKY NOTES sind spezielle ToolTips, also kleine Minifenster, die wie Post-Its aussehen und die beim Überfahren mit der Maus auftauchen. Sie können diese ToolTips für Hintergrundinfos nutzen. So werden die STICKY NOTES konfiguriert:

"[note_example]": {
    "text_hover" : "Wenn Sie hier mit der Maus drüberfahren ...",
    "text_note" : "... wird eine kleine Notiz eingeblendet.",
    "make_italic" : "true",
    "cursor_style" : "help"
}

Konkretes Beispiel: Wenn Sie hier mit der Maus drüberfahren ... ... dann wird ein kleine Notiz eingeblendet

Parameterübersicht STICKY NOTES:

Option	Description	Possible Values
text_hover	Text that will show the note when mouse is over this text	Plain text, no HTML
text_note	The text of the note that will appear	Plain text, no HTML
make_italic	Show note text in italic style?	"true" or "false"
cursor_style	Style of the cursor when hovering over the text	Valid CSS cursor style. See this link for reference ⧉.

Modal Windows

TRIGGER

"[modal_*]"

Mit MKDOCS Substitute können Sie Modal-Fenster erzeugen. MKDOCS Substitute nutzt dabei die Funktionalität von micromodal.js. Einen Link zur Javascript-Bibliothek müssen Sie für eine Nutzung in der mkdocs.yaml einfügen:

extra_javascript:  
    - https://unpkg.com/micromodal/dist/micromodal.min.js

Modal-Fenster haben verschiedene Eigenschaften, die Sie in der substitutions.json einstellen können:

"[modal_5]": {
    "trigger": "OPEN THE MODAL WINDOW",
    "trigger_text_color" : "blue",
    "trigger_font_weight" : "bold",
    "title" : "THIS IS THE TITLE OF A MODAL WINDOW",
    "content" : "<small>Lorem ipsum dolor sit amet consectetur adipisicing elit. Vel, voluptatum. Magni hic, voluptate debitis esse corporis dolor laudantium quae quo!</small>",
    "padding" : "25px",
    "max_width" : "600px",
    "button_text" : "Got It!",
    "space_title_content" : "1rem",
    "space_content_bottom" : "1rem"

},

Anmerkung: Alle MODAL Fenster können per ESC geschlossen werden.

Beispiel für ein Modal-Fenster:

OPEN THE MODAL WINDOW

Es stehen folgende Parameter zur Gestaltung der Modal-Fenster zur Verfügung:

Parameterübersicht MODALFENSTER:

Option	Description	Possible Values
trigger	Trigger Text for click to open Modal	Plain Text - do not use additional HTML here
trigger_text_color	The Color of the Trigger Text	HEX Value or valid HTML Color name
trigger_font_weight	The Font-Weight of the Trigger Text	"normal" or "bold"
title	The Title of the Modal	Text, can include HTML
content	The content if the Modal	Text, can include HTML
padding	The Padding of the Modal content	Integer number e.g. 20 - padding to all sites of Modal in px
max_width	Define the Maximum Width of the Modal	The width of the Modal at maximum in px
button_text	Text on the Close Button	This is the Text on the MODAL Close Button
space_title_content	Space between Title and Content	Integer number e.g. 20 (~ 20px)
space_content_bottom	Space between Content and Bottom	Integer number e.g. 20 (~ 20px)

Newsticker

TRIGGER

"[news_*]"

MKDOCS Substitute kann einen einfachen Newsticker im Text platzieren - so sieht das in der in der substitutions.json:

"[news_3]": {
    "text" : "Lorem ipsum dolor sit amet consectetur adipisicing elit. Vel, voluptatum. Magni hic, voluptate debitis esse corporis dolor laudantium quae quo!",
    "background_color" : "#f9f9f9",
    "text_color" : "darkred",
    "font_weight" : "bold",
    "speed" : "20"
},

So sieht der Newsticker aus :

Das sind die Parameter zur Gestaltung des Newstickers:

Parameterübersicht NEWSTICKER:

Option	Description	Possible Values
background-color	Background-Color of the newsticker	"success", "alert", "warning", "info", HEX-Value or Valid HTML Color name
text-color	Text-Color of the badge	HTML Valid Colorname or HEX Value
text	Text of the Badge	"true" or "false"
font-weight	The Weight of the Newsticker Text	"bold" or "normal"
speed	The speed of the Newsticker	Integer value (seconds)

SEO Funktionen

TRIGGER

Kein Trigger notwendig. Funktion ist automatisch aktiviert.

MKDOCS Substitute bietet die Möglichkeit, auf in der Präamble der Markdown Dateien festgelegte Beschreibungen und Keywords zu zugreifen und diese als META-Description bzw. META-Keywords beim Erzeugen der Seiten zu generieren. Die Keywords und Beschreibungen der Präamble werden also durch echte -Tags ersetzt.

Diese Funktion ist mit der Installation von MKDOCS Substitute automatisch aktiviert - sie müssen dafür nichts in die mkdocs.yaml oder die substitute.json eintragen. Sie sollten dann aber andere Plugins mit einem ähnlichen Zweck deaktivieren, da doppelte META Einträge zu Indizierungsfehlern bei den Crawlern der Suchmaschinen führen.

Findet MKDOCS Substitute zwei völlig identische Einträge - weil ein Eintrag z.B. vom Theme selbst über den Description-Tag erstellt wurde - wird es nur einen Eintrag in der Erstellung der HTML Output Datei zulassen.

So sehen dann die Einträge in der Präamble einer Markdown-Datei aus:

---
title: Willkommen bei Peter Killert.
description: Die Startseite der Homepage von Peter Killert.
keywords:
    - Killert
    - Autor
    - Quadrizepssehnenruptur
---

Im Seitenquelltext erscheinen dann diese <meta>-Tags

FAQ

Hier einige Infos und Antworten zu Fragen, die bei der Nutzung von MKDOCS Substitute auftreten können:

Was bedeutet 'Valid HTML Code Color Name'?

Um in HTML eine Farbe zu definieren können Sie statt eines HEX Codes auch den Namen einer Farben nehmen. Diese Farbnamen sind festgelegt und werden von allen gängigen Browsern verstanden. Eine Übersicht über diese Farbnamen finden Sie hier: www.w3schools.com/tags/ref_colornames.asp ⧉

Kann ich die Ersetzungen auch innerhalb von HTML Tag einsetzen?

Ja, das ist möglich. Wenn Sie beispielsweise eine Ersetzung innerhalb eines DIV Tags platzieren, sollte das funktionieren.

Warum haben die vorgefertigten Elemente nicht mehr Parameter für die Gestaltung?

Bei der Auswahl der Parameter habe ich mich auf die gängisten, wichtigsten Element konzentriert. Sie können aber ein Element mit einem weiteren TAG und einer eigenen CSS Klasse 'umschliessen' um noch mehr Styling vorzunehmen.

Ich habe in dem Ersetzungstext ein Anführungszeichen. Wie setze ich das in der JSON Datei?

Die Anführungszeichen in der JSON Datei begrenzen den Ersetzungstext. Soll in dem Text selbst aber ebenfalls ein Anführungszeichen stehen, so müssen sie dies mit dem Escape Slash in den Ersetzungstext schreiben. Also als \""

Updates

MKDOCS Substiute wird regelmässig aktualisiert und fehlerbereinigt. Manchmal kommen auch kleine Neuerungen hinzu. Die aktuelle Version fragen Sie über die Kommandozeile mit

pip show mkdocs-substitute-plugin

ab.

Ein gezieltes Update des mkdocs-substitute-plugin erzwingen sie mit

pip install mkdocs-substitute-plugin

Uninstall

Sollten Sie - aus welchen Gründen auch immer - dieses Plugin nicht mehr benötigen, dann können Sie das Pakete auch deinstallieren:

pip uninstall mkdocs-substitute-plugin

Beachten Sie dabei, dass Sie auch diese Einträge in der mkdocs.yaml löschen oder mit einem vorangestellten "#" auskommentieren müssen:

plugins:
    #- substitute-plugin:
    #    substitutions_file: substitutions.json

Die gesamte Funktionalität geht dadurch natürlich verloren. Die Platzhalter erscheinen dann in ihren Quelldateien dann auch genauso, wie sie platziert wurden ohne Ersetzungen. Die müssten Sie dann ggf. ebenfalls entfernen.

Lizenzierung

Dieses Plugin darf frei genutzt werden. Bei regelmässiger, nicht-kommerzieller Nutzung, freue ich mich über eine kleine Anerkennung per PayPal. Bei einer kommerziellen Nutzung bitte ich um eine Zahlung von einmalig 20,- EUR ebenfalls per Paypal. Ich untersage eine kommerzielle Nuztzung nicht und schränke diese auch nicht ein - diese Bitte um diese überschaubare, angemessene Zahlung ist ein Appell an ihre Fairness. Solche sinnvollen Projekte sind ohne erheblichen zeitliche Aufwand nicht umsetzbar.

Support