- CSS 89.6%
- HTML 10.4%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| example | ||
| overrides | ||
| .gitignore | ||
| mkdocs.base.yml | ||
| README.md | ||
| requirements.txt | ||
Julscha mkdocs-Theme
Geteilte mkdocs-Basis für alle Julscha-Doku-Repos. Enthält die Eltern-Config, das
Julscha-Design (Tone anthracite, Accent indigo) und die selbst ausgelieferten
Schriften. Ein Konsument bringt nur seine Inhalte und vier Zeilen Config mit.
Dieser Ordner ist noch kein Git-Repo. Ziel-Remote: code.julscha.de/libs/mkdocs-theme,
Branch main.
Aufbau
mkdocs.base.yml Eltern-Config, ohne jeden Dateisystempfad
requirements.txt mkdocs + mkdocs-material exakt gepinnt
overrides/
main.html hängt julscha.css in {% block extrahead %} ein
assets/
stylesheets/julscha.css
fonts/ Hanken Grotesk 400/500/600/700, JetBrains Mono
images/ logo.png (128px), favicon.png (64px)
vendor/mermaid.min.js mermaid 11.17.2, selbst ausgeliefert
example/ baubares Minimalbeispiel zum Designprüfen
Benutzung
Das Theme wird im CI nach .mkdocs-theme/ ausgecheckt — das macht der Workflow
mkdocs-pages.yml aus libs/ci-templates. Das Doku-Repo enthält:
# mkdocs.yml
INHERIT: .mkdocs-theme/mkdocs.base.yml
site_name: Julscha Status
site_url: https://pages.julscha.de/infra/status/docs/
theme:
custom_dir: .mkdocs-theme/overrides
nav:
- Start: index.md
# .forgejo/workflows/ci.yml
on:
push:
branches: ['**']
pull_request:
jobs:
scan:
uses: libs/ci-templates/.forgejo/workflows/trivy-scan.yml@main
docs:
needs: scan
if: ${{ !cancelled() && !failure() }}
uses: libs/ci-templates/.forgejo/workflows/mkdocs-pages.yml@main
secrets: inherit
Lokal statt des CI-Klons ein Junction auf diesen Ordner:
cd <doku-repo>
cmd /c mklink /J .mkdocs-theme ..\libs\mkdocs-theme
mkdocs build --strict
.mkdocs-theme/ gehört in die .gitignore des Konsumenten.
Warum die Dateien so aussehen
Drei Eigenheiten von mkdocs bestimmen die Form, nicht Geschmack:
extra_cssist hier unbenutzbar. mkdocs verlangt, dass jederextra_css-Eintrag innerhalb vondocs_dirliegt;julscha.cssliegt aber im Theme. Statische Dateien untercustom_dirwerden unverändert in die Site kopiert, deshalb hängtoverrides/main.htmldas Stylesheet in{% block extrahead %}ein. Dieser Block rendert als Letztes im<head>, also nach Materials eigenem CSS.INHERITersetzt Listen, statt sie zu mischen.pluginsundmarkdown_extensionsstehen deshalb in der Dict-Schreibweise. Wer sie im Konsumenten als Liste notiert, wirft alles aus dieser Datei weg.- Relative Pfade in der Eltern-Config sind unsicher, weil die gemergte Config den
Pfad des Kindes trägt.
mkdocs.base.ymlenthält deshalb keinen Dateisystempfad;theme.custom_dirsetzt der Konsument.theme.logo/theme.faviconsind reine Ausgabe-Pfade und dürfen hier stehen.
Design
Die Tokens in julscha.css sind 1:1 aus
julscha-frontend/packages/ui-library/src/styles/_theme.scss (Tone anthracite,
Accent indigo) und _fonts.scss übernommen. Die öffentliche Seite /branding liest
dieselben Tokens live — wer dort etwas ändert, zieht es hier nach.
Nur dunkel, wie Julscha selbst: palette.scheme: slate, kein Hell/Dunkel-Umschalter.
Mermaid wird ausschließlich über Materials --md-mermaid-*-Variablen eingefärbt. SVG-
fill/stroke lösen kein var() auf, deshalb führt jeder andere Weg zu hellen Kästen
im dunklen Layout.
Mermaid selbst liegt als overrides/assets/vendor/mermaid.min.js im Theme, 3,5 MB.
Material würde es sonst von unpkg.com nachladen — es prüft aber vorher
typeof mermaid == "undefined", und main.html definiert den Global vorher. Dadurch
geht kein Request nach außen, und mermaid.initialize() mit den Theme-Variablen macht
weiterhin Material. Das Script-Tag steht nur auf Seiten, die wirklich ein Diagramm
enthalten (page.content-Prüfung) — und genau deshalb ist navigation.instant
abgeschaltet: Instant-Loading würde dieses seitenweise Tag nicht neu auswerten.
Zum Aktualisieren:
curl -sL -o overrides/assets/vendor/mermaid.min.js \
https://unpkg.com/mermaid@11.17.2/dist/mermaid.min.js
Die Hauptversion muss bei 11 bleiben, solange Material mermaid@11 erwartet.
Die Schriften liegen als woff2 im Ordner und werden per @font-face geladen,
theme.font: false schaltet Materials Google-Fonts-Einbindung ab. Es darf kein Request
an fonts.googleapis.com entstehen.
Vom Logo existiert keine Vektorfassung. logo.png und favicon.png sind aus
logos/tools/transparent-version-logo.png heruntergerechnet; kommt eine SVG-Fassung,
ersetzt sie beide.
Nach dem Anlegen des GitLab-Projekts
CI_JOB_TOKEN darf fremde Projekte erst klonen, wenn das Zielprojekt den Aufrufer
erlaubt. Also entweder jedes Doku-Projekt unter
Settings → CI/CD → Job token permissions dieses Projekts eintragen, oder dieses Projekt
auf Sichtbarkeit „Internal" stellen. Ohne das eine oder andere scheitert jeder
Pages-Build am Klon.