MKDOCS Substitute

For several years, all of my pages have been generated using a static website generator called "mkdocs" ⧉. This tool is very simple and meets almost all of my requirements, especially when used with the "Material" ⧉. However, I'm always missing a few features, and at some point I started to explore this tool's plugins.

Mkdocs Substitute has become a powerful extension of mkdocs/Material. As the plugin's name suggests, specific text passages/placeholders in Markdown source files can be replaced with any text modules. What's more... with MKDOCS Substitute, you can insert elements such as alerts, badges, toast, freely available icons, modal windows, social media widgets, etc., without having to deal with complicated JavaScript functions or long HTML elements.

INSTALLATION

Open the Windows Terminal application and enter this command:

pip install mkdocs-substitute-plugin

The tool should install without any problems. Note the minimum version requirements for mkdocs and upgrade if necessary. MKDOCS Substitute was tested and developed in Python with MKDOCS and Material.

The plugin is enabled in mkdocs.yaml as follows:

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

substitutions.json
The substitutions.json file is mandatory. This file defines the substitutions. This guide explains how this works for individual elements. To start, create an empty substitutions.json file with this content. This file should be located in the same directory as mkdocs.yaml (usually the root directory of your project).

BASICS - Simple Substitutions

First, you can use MKDOCS SUBSTITUTE to create any placeholder you want, with text that you want to replace everywhere on all your pages. Example: You want to include a notice on several pages in your project, informing visitors to your site that they can contact you via email at any time. The corresponding link, which opens the visitors' default email program, is inserted at the same time. This would then look like this in the substitutions.json:

Then simply insert the placeholder into your Markdown files...

Instead of [ MY_HTML_BLOCK ], Hello World will appear right-aligned in red.

This allows you to define entire HTML blocks and insert them as building blocks at any time. The possible applications are diverse.

MKDOCS Substitute also offers many predefined substitutions. These are defined by beginning a phrase with a square bracket. These elements are now presented:

Icons von PICTOGRAMMERS

Everyone probably knows Fontawesome ⧉ – a web font that contains thousands of icons that can be used in a variety of ways on your website. However, the number of freely available icons is limited. Pictogrammers offers a free alternative. More than 7,000 icons are available there.

To do this, the CSS file for the PICTOGRAMMERS web fonts must be inserted into the mkdocs.yaml file:

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

Icons from there can be easily embedded using MKDOCS Substitute.

Here's how to define an ICON in your substitutions.json:

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

The name account-convert comes from the overview of available icons, which you can find here:

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

You can also embed these icons in an HTML tag embed so that these icons, for example, take on a different size.

Display the icon larger:

would then result in this display:

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