mkdocs-kern-ux

Live-Demo: https://kern-ux-theme-for-mkdocs-fda32d.usercontent.opencode.de

Alle Bausteine des Themes zum Ausprobieren – mit Suche, Hell-/Dunkel-Umschalter und mobiler Ansicht.

MkDocs-Theme auf Basis des KERN Design-Systems – dem offenen Design-System für die öffentliche Verwaltung, initiiert von Hamburg und Schleswig-Holstein.

Das Theme ist die Nachnutzung dieses Systems durch eine Kommune, kein offizielles Angebot des KERN-Projekts. Es ist das Schwesterprojekt des KERN-UX-Themes für WordPress und folgt demselben Bauprinzip.

Grundidee: Vendor und Bridge

Schicht	Inhalt	Wer pflegt sie
Vendor	Der komplette KERN-Kit (@kern-ux/native) und highlight.js, unverändert unter src/mkdocs_kern_ux/kern-ux/vendor/	Upstream; Aktualisierung mit npm run vendor:update
Bridge	Templates, kern-ux/css/kern-ux.css, kern-ux/js/*.js	dieses Repository

Die Bridge enthält keine eigenen Designwerte. Sie referenziert ausschließlich KERN-Token (--kern-*) und übersetzt das von MkDocs und Python-Markdown erzeugte Markup darauf. Deshalb wirken heller und dunkler Modus sowie künftige KERN-Updates automatisch, und ein Kit-Update bleibt konfliktfrei.

Anpassungen gehören nie in den Vendor-Ordner – er wird bei jedem Sync vollständig ersetzt.

Installation

pip install mkdocs-kern-ux

# mkdocs.yml
theme:
  name: kern-ux

Mehr braucht es nicht: Schriften, Stylesheets und Skripte liegen im Paket und werden beim Bauen in die Site kopiert. Es wird kein CDN kontaktiert – für Angebote der öffentlichen Verwaltung ist das eine Anforderung, keine Zugabe.

Empfohlene Erweiterungen

markdown_extensions:
  - abbr
  - admonition
  - attr_list
  - def_list
  - fenced_code
  - footnotes
  - md_in_html
  - tables
  - toc:
      permalink: true
  - pymdownx.details      # aufklappbare Hinweise (???)
  - pymdownx.mark         # ==Hervorhebung==
  - pymdownx.tilde        # ~~durchgestrichen~~
  - pymdownx.tasklist:
      custom_checkbox: false

plugins:
  - search:
      lang: de

Die pymdownx.*-Erweiterungen stammen aus pymdown-extensions (pip install "mkdocs-kern-ux[recommended]"). Das Theme läuft auch ohne sie – die Bridge deckt beide Ausgabeformen ab.

Optionen

Wo die mitgelieferten Themes mkdocs und readthedocs bereits eine Option kennen, trägt sie hier denselben Namen und dieselbe Bedeutung.

Kompatibel zu den mitgelieferten Themes

Option	Vorgabe	Bedeutung
highlightjs	true	Syntaxhervorhebung mit highlight.js (lokal)
hljs_languages	[]	Zusatzsprachen, z. B. [rust, php]
hljs_style	github	Farbschema hell
hljs_style_dark	github-dark	Farbschema dunkel
analytics.gtag	null	Google-Analytics-Kennung (siehe Hinweis unten)
analytics.anonymize_ip	false	IP-Anonymisierung an gtag durchreichen
include_homepage_in_sidebar	true	Startseite in der Seitenleiste zeigen
prev_next_buttons_location	bottom	top, bottom, both, none
navigation_depth	4	Tiefe des Navigationsbaums
titles_only	true	false zeigt die Gliederung der aktiven Seite in der Seitenleiste
sticky_navigation	true	Seitenleiste und Gliederung laufen mit
collapse_navigation	true	Nur der aktive Abschnitt ist aufgeklappt
logo	null	Logo, relativ zu docs_dir
color_mode	auto	auto, light, dark
user_color_mode_toggle	true	Umschalter in der Kopfzeile
include_search_page	true	Seite search.html erzeugen
search_index_only	false	Nur den Suchindex schreiben
locale	de	Sprache der Seite und Stemming der Suche

Nicht übernommen: nav_style und shortcuts aus dem mkdocs-Theme. KERN kennt keine Navbar-Varianten, und Tastaturkürzel ohne sichtbare Erklärung schaffen mehr Verwirrung als Nutzen.

Eigene Optionen

Option	Vorgabe	Bedeutung
show_toc	true	Gliederungsspalte rechts
toc_depth	3	Tiefste Überschriftenebene in der Gliederung
toc_scrollspy	true	Sichtbaren Abschnitt markieren
show_breadcrumb	true	Brotkrumenpfad
show_edit_link	true	„Diese Seite bearbeiten“ (braucht repo_url + edit_uri)
show_search	true	Suchknopf in der Kopfzeile
copy_code	true	Kopierknopf an Codeblöcken
admonition_icons	true	KERN-Symbole in Hinweisen
content_width	50rem	Lesebreite des Fließtexts
max_width	90rem	Gesamtbreite der Seite
logo_alt	''	Alternativtext des Logos; leer = dekorativ
favicon	null	Favicon, relativ zu docs_dir
homepage_title	null	Beschriftung der Startseite im Brotkrumenpfad
footer_text	''	Freier Text in der Fußzeile
footer_links	[]	Einträge {text, href, external}; href darf auf die Quelldatei zeigen (impressum.md) oder eine fertige Adresse sein
show_kern_credit	true	Hinweis auf KERN und die Kit-Version

Texte

Jeder sichtbare Text ist einzeln überschreibbar; die Schlüssel beginnen mit lang_ (siehe src/mkdocs_kern_ux/mkdocs_theme.yml):

theme:
  name: kern-ux
  lang_search: Volltextsuche
  lang_edit: Seite im Repository bearbeiten

Die Schlüssel sind bewusst flach: MkDocs ersetzt ein Mapping vollständig, ein einzelner Override würde in einer verschachtelten Struktur alle übrigen Texte löschen.

Eigene Anpassungen

theme:
  name: kern-ux
  custom_dir: overrides

extra_css:
  - assets/eigene.css

{# overrides/main.html #}
{% extends "base.html" %}

{% block footer %}
  <footer class="kux-footer">…</footer>
{% endblock %}

Verfügbare Blöcke: site_meta, htmltitle, styles, libs, analytics, extrahead, body_class, header, site_name, search_button, site_nav, content, repo, next_prev, toc, footer, search_dialog, scripts.

Alle Optionen stehen in den Templates als kux.<option> bereit – nicht als config.theme.<option>. base.html mischt die Vorgaben dort noch einmal selbst, damit das Theme auch als reines custom_dir vollständig funktioniert.

Als custom_dir ohne Paketinstallation

theme:
  name: null
  custom_dir: pfad/zu/src/mkdocs_kern_ux
  # In dieser Betriebsart liest MkDocs mkdocs_theme.yml nicht - diese vier
  # Vertragsschluessel muessen deshalb selbst gesetzt werden:
  locale: de
  static_templates: [404.html]
  include_search_page: true
  search_index_only: false

Alle übrigen Optionen greifen auch hier auf ihre Vorgaben zurück; die gebauten Seiten sind Zeichen für Zeichen identisch mit der Paketinstallation.

Aktualisieren

npm run kern:check      # gibt es eine neuere KERN-Version?
npm run kern:update     # KERN installieren und ins Theme kopieren
npm run hljs:update     # highlight.js aktualisieren
npm run vendor:update   # beides

Die Sync-Skripte ersetzen den Vendor-Ordner vollständig, schreiben VERSION und SYNC.txt, kopieren die Lizenztexte zusätzlich als .txt und ziehen kern_version bzw. hljs_version in mkdocs_theme.yml nach. Bricht ein Update, weil eine erwartete Datei fehlt, meldet das Skript das laut, statt still 404er auszuliefern.

Nach einem Update lohnt ein Blick auf demo/docs/komponenten/tabellen.md: dort stehen Markdown-Tabelle und handgeschriebene kern-table untereinander, sodass ein geändertes Kit-Design sofort auffällt.

Mit npm run kern:sync:prune bzw. hljs:sync:prune lässt sich der Vendor auf das tatsächlich Geladene eindampfen (rund 8 MB → 2 MB). Voreingestellt ist die vollständige, unveränderte Kopie.

Demo

Online: https://kern-ux-theme-for-mkdocs-fda32d.usercontent.opencode.de/ – wird bei jedem Push auf main von der CI neu gebaut.

Ein fertiger Offline-Export liegt unter demo/export/ – index.html einfach im Browser öffnen. Selbst bauen und live anschauen:

npm install && npm run vendor:sync   # nur nötig, um den Vendor zu erneuern
pip install -e ".[recommended]"
mkdocs serve -f demo/mkdocs.yml

demo/mkdocs.minimal.yml baut dieselbe Site ohne pymdown-extensions und mit serverseitiger Hervorhebung (codehilite). Beide Profile zu bauen ist der Regressionstest der Bridge:

mkdocs build --strict -f demo/mkdocs.yml
mkdocs build --strict -f demo/mkdocs.minimal.yml
mkdocs build -f demo/mkdocs.export.yml   # Offline-Export nach demo/export/

Dazu ein Prüflauf im echten Browser – er misst die Layout-Geometrie jeder Demoseite und bedient Suche, Kopierknopf und Design-Umschalter:

npm run demo:serve     # in einem Terminal
npm run demo:check     # im zweiten

Weicht eine Seite ab, greift Inhalt ins Seitenlayout durch. Genau das passiert zum Beispiel, wenn der Seitenrahmen kern-container trägt und eine Seite ein kern-grid enthält.

Stolperfallen

code { font-family: … } in eigenem CSS wirkt nicht. Der KERN-Kit setzt *:not(i) { font-family: … }. Diese Regel schlägt einen bloßen Elementselektor. Schreiben Sie .kux-prose code { … }.

Serverseitige Hervorhebung und highlight.js schließen sich aus. Wer codehilite oder pymdownx.highlight nutzt, färbt bereits beim Bauen; dann highlightjs: false setzen und ein Pygments-Stylesheet über extra_css einbinden. Das Theme lässt vorgefärbte Blöcke unangetastet.

edit_uri bei selbst gehostetem GitLab. MkDocs leitet die Bearbeiten-URL nur für github.com, gitlab.com und bitbucket.org automatisch ab. Für openCoDE/GitLab: edit_uri: -/edit/main/docs/.

Schriftanzeige. Der Kit liefert keine font-display-Angabe. Das Theme lädt die beiden genutzten Schnitte deshalb vorab (rel=preload).

analytics.gtag bindet ein Skript von Google ein. Voreingestellt ist die Option leer. Wer sie setzt, braucht eine eigene Rechtsgrundlage und muss die Datenschutzerklärung ergänzen.

Browser-Untergrenze. Der Suchdialog nutzt <dialog>.showModal(); fehlt die Unterstützung, führt der Suchknopf zur Seite search.html. Die Bridge nutzt :is() – seit 2021 überall verfügbar.

Barrierefreiheit

Sprunglink, Landmarken, sichtbarer Fokus (4 px, aus dem Kit), Zustände nie nur über Farbe, scrollbare Codeblöcke mit Tastaturzugang, fokussierbare Ankerlinks, Berücksichtigung von forced-colors und prefers-reduced-motion, und ohne JavaScript bleibt alles bedienbar. Details: demo/docs/referenz/barrierefreiheit.md.

Veröffentlichen

Wie das Theme gebaut, weitergegeben und auf PyPI veröffentlicht wird, steht Schritt für Schritt in VEROEFFENTLICHEN.md – ohne Python-Vorwissen lesbar.

Lizenz

Der Theme-Code steht unter der EUPL-1.2 (siehe LICENSE). Der gebündelte KERN-Kit steht ebenfalls unter EUPL-1.2, highlight.js unter BSD 3-Clause, die Schriften unter der SIL Open Font License 1.1 – siehe THIRD-PARTY.md.