Metadata-Version: 2.5
Name: mkdocs-kern-ux
Version: 0.2.0
Summary: MkDocs-Theme auf Basis des KERN-UX Design-Systems (@kern-ux/native).
Project-URL: Homepage, https://kern-ux.de
Project-URL: Documentation, https://kern-ux-theme-for-mkdocs-fda32d.usercontent.opencode.de/
Project-URL: Source, https://gitlab.opencode.de/sgemlichheim/kern-ux-theme-for-mkdocs
Project-URL: Issues, https://gitlab.opencode.de/sgemlichheim/kern-ux-theme-for-mkdocs/-/issues
Author: Samtgemeinde Emlichheim, Michi91
License-Expression: EUPL-1.2
License-File: LICENSE
License-File: THIRD-PARTY.md
Keywords: accessibility,barrierefreiheit,bitv,kern,kern-ux,mkdocs,mkdocs-theme
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: MkDocs
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: German
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Documentation
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.9
Requires-Dist: mkdocs<2,>=1.6
Provides-Extra: recommended
Requires-Dist: pygments>=2.16; extra == 'recommended'
Requires-Dist: pymdown-extensions>=10.0; extra == 'recommended'
Description-Content-Type: text/markdown

# mkdocs-kern-ux

MkDocs-Theme auf Basis des [KERN Design-Systems](https://www.kern-ux.de) – 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](https://gitlab.opencode.de/sgemlichheim/kern-ux-theme-for-wordpress)
und folgt demselben Bauprinzip.

**Demo:** <https://kern-ux-theme-for-mkdocs-fda32d.usercontent.opencode.de/>

## 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

```bash
pip install mkdocs-kern-ux
```

```yaml
# 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

```yaml
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`):

```yaml
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

```yaml
theme:
  name: kern-ux
  custom_dir: overrides

extra_css:
  - assets/eigene.css
```

```jinja
{# 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

```yaml
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

```bash
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:

```bash
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:

```bash
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:

```bash
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](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`.
