Zum Inhalt

Wiki-Deployment — MkDocs Material → poe.wanitzek.com/wiki/

Statisches Wiki rendert die 105 .md aus diesem Repo zu HTML, deployt auf den bestehenden PoB-Webapp-LXC.

Live-URL

https://poe.wanitzek.com/wiki/

Stack

Komponente Wert
Generator MkDocs Material 9.x in venv /tmp/mkdocs-venv/ (lokal)
Theme Material mit Custom-Hero + Tooltips
Search Lunr.js (DE+EN), eingebaut
Hosting nginx auf 192.168.0.191 (LXC, kein SSL extra)
Deploy rsync von lokal → /var/www/pob/wiki/

Verzeichnisstruktur

PathOfExile_Full/
├── index.md                 ← Wiki-Landing mit Hero + Cards
├── assets/                  ← Custom CSS + JS (Tooltips)
│   ├── styles.css
│   └── uniques.js
├── _site_build/             ← MkDocs-Workspace
│   ├── mkdocs.yml
│   ├── overrides/main.html  ← Hero-Template-Override
│   ├── docs/                ← Symlinks zu Schwester-Ordnern
│   └── site/                ← Build-Output (ignored)
├── mechanics/
│   ├── _index.md            ← Original-Index-Datei
│   └── index.md             ← Symlink → _index.md (für mkdocs)
├── crafting/
│   ├── _index.md
│   ├── index.md             ← Symlink → _index.md
│   └── ...
└── ...

Build + Deploy (eine Zeile)

cd ~/Dokumente/PathOfExile_Full/_site_build && \
  /tmp/mkdocs-venv/bin/mkdocs build && \
  rsync -aH --delete site/ root@192.168.0.191:/var/www/pob/wiki/

Build-Zeit: ~3 Sekunden. Deploy: ~5 Sekunden.

Erste Einrichtung — Reproduktion

# 1. MkDocs in venv (CachyOS hat managed Python)
python3 -m venv /tmp/mkdocs-venv
/tmp/mkdocs-venv/bin/pip install mkdocs-material

# 2. _site_build-Layout (siehe oben) erstellen
cd ~/Dokumente/PathOfExile_Full
mkdir -p _site_build/docs
cd _site_build/docs
for d in mechanics crafting items gems drops builds economy league workflows; do
  ln -sf ../../$d $d
done
ln -sf ../../index.md index.md
ln -sf ../../META.md META.md
ln -sf ../../assets assets

# 3. Index-Symlinks für mkdocs section-roots
cd ~/Dokumente/PathOfExile_Full
for f in $(find . -name "_index.md" -not -path "./_site_build/*" -not -path "./webapp/*"); do
  ln -sf _index.md "$(dirname "$f")/index.md"
done

# 4. Build
cd _site_build && /tmp/mkdocs-venv/bin/mkdocs build

nginx-Konfiguration (auf 192.168.0.191)

In /etc/nginx/sites-available/pob vor dem catch-all location / block einfügen:

# Wiki — statisches MkDocs-Material site
location ^~ /wiki/ {
    alias /var/www/pob/wiki/;
    try_files $uri $uri/ $uri.html /wiki/index.html =404;

    # HTML kurz cachen, Assets lang
    location ~* \.(html|xml|json)$ {
        expires 5m;
        add_header Cache-Control "public, max-age=300";
    }
    location ~* /wiki/assets/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

location = /wiki {
    return 301 /wiki/;
}

Reload: systemctl reload nginx

Stolperfallen die wir gelöst haben

1. docs_dir darf nicht parent von mkdocs.yml sein

Symptom: ERROR - Config value 'docs_dir': The 'docs_dir' should not be the parent directory of the config file.

Lösung: Subdirectory _site_build/ mit mkdocs.yml + docs/ (Symlinks zu echten Inhalten).

2. _index.md macht URL /wiki/section/_index/ statt /wiki/section/

Symptom: Navigation-Tabs (Material navigation.tabs-Feature) führen zu 403/404.

Lösung: - index.md als Symlink → _index.md in jeder Sektion (mkdocs nimmt index.md als Section-Root mit navigation.indexes) - _index.md aus Build excluden (sonst doppelte URLs) - Cards-Hrefs: crafting/ (NICHT crafting/_index/)

3. Material's navigation.instant cacht alte Versionen

Symptom: Nach Deploy zeigt Browser noch alte Tab-Hrefs trotz korrekter Server-Files.

Lösung: ?_cb=<timestamp> Cache-Bypass beim Test, oder Hard-Reload (Strg+Shift+R).

4. H3-Pattern für Unique-Items

Konvention im Repo: ### Name — Base (Req N) — em-dash, Klammer mit Req-Level. Konsistenz verifiziert über alle 14 Slot-Files (1562 Uniques).

assets/uniques.js parsed dieses Pattern und wandelt H3 + folgendes <ul> in .poe-tooltip-Cards.

5. exclude_docs Pattern

exclude_docs: |
  webapp/
  site/
  node_modules/
  .git/
  .claude/
  _templates/
  mkdocs.yml
  README.md
  _index.md
  */_index.md
  **/_index.md
  *.html
  *.json
  *.py
  *.txt

README.md wird excluded weil index.md die Landing ist.

Custom Features

Hero-Section auf Landing

overrides/main.html extended base.html, rendert nur wenn page.is_homepage. Hero hat: - PoE-Goldgradient-Title - Suchleiste die Material's eingebaute Suche triggert - 6 Use-Case-Cards (Build/Crafting/Mechanik/Items/Endgame/Wirtschaft) - Quick-Stats-Strip

PoE-Tooltip-Renderer für Uniques

assets/uniques.js läuft auf jeder Page nach DOMReady (oder via Material's document$ Subscriber): - Findet H3 mit Pattern Name — Base (Req N) - Wandelt in .poe-tooltip Cards mit: - Goldener Name (Unique-Color #af6025) - Base + Required Level - Trenner (PoE-Style) - Mods in PoE-Blau (#8888ff) mit <span class="poe-num"> Zahlen-Highlight - Skill-Grants in helleres Cyan (#71d5ff) - "Corrupted"-Marker rot - Bei ≥5 Tooltips: gruppiert in Grid (Cards nebeneinander auf grossen Screens)

CSS in assets/styles.css: PoE-Goldakzent (#c8aa6e), dunkles Tooltip-Background-Gradient, responsives Grid.

Versionen-Update bei .md-Änderung

Nur mkdocs build && rsync — keine Indexer-Reruns nötig solange wir kein RAG haben. Material's Lunr-Index wird beim Build automatisch neu gebaut.

Querverweise