No description
  • CSS 89.6%
  • HTML 10.4%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-07 04:45:22 +01:00
example fix: update site_url in README and example mkdocs.yml for consistency 2026-10-09 23:04:58 +02:00
overrides feat: Julscha-themed mkdocs base config, overrides and self-hosted fonts (ALLGEMEIN-27) 2026-10-09 22:57:21 +02:00
.gitignore feat: Julscha-themed mkdocs base config, overrides and self-hosted fonts (ALLGEMEIN-27) 2026-10-09 22:57:21 +02:00
mkdocs.base.yml feat: Julscha-themed mkdocs base config, overrides and self-hosted fonts (ALLGEMEIN-27) 2026-10-09 22:57:21 +02:00
README.md fix: update CI workflow references in README for accuracy 2026-11-07 04:45:22 +01:00
requirements.txt feat: Julscha-themed mkdocs base config, overrides and self-hosted fonts (ALLGEMEIN-27) 2026-10-09 22:57:21 +02:00

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:

  1. extra_css ist hier unbenutzbar. mkdocs verlangt, dass jeder extra_css-Eintrag innerhalb von docs_dir liegt; julscha.css liegt aber im Theme. Statische Dateien unter custom_dir werden unverändert in die Site kopiert, deshalb hängt overrides/main.html das Stylesheet in {% block extrahead %} ein. Dieser Block rendert als Letztes im <head>, also nach Materials eigenem CSS.
  2. INHERIT ersetzt Listen, statt sie zu mischen. plugins und markdown_extensions stehen deshalb in der Dict-Schreibweise. Wer sie im Konsumenten als Liste notiert, wirft alles aus dieser Datei weg.
  3. Relative Pfade in der Eltern-Config sind unsicher, weil die gemergte Config den Pfad des Kindes trägt. mkdocs.base.yml enthält deshalb keinen Dateisystempfad; theme.custom_dir setzt der Konsument. theme.logo/theme.favicon sind 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.