65 lines
2.6 KiB
Markdown
65 lines
2.6 KiB
Markdown
# MkDocs to PDF Workflow mit Pandoc & Docker
|
||
|
||
Dieses Projekt enthält ein Bash-Skript und eine Umgebung zum automatischen Konvertieren von MkDocs-Markdown-Dateien in PDF-Dateien mit individuellen Templates.
|
||
|
||
## Features
|
||
|
||
- Automatische Erstellung von PDFs aus Markdown-Dateien im `mkdocs/docs` Verzeichnis
|
||
- Nutzung von `pandoc` in einem Docker-Container für Konsistenz und Portabilität
|
||
- Unterstützung von LaTeX-Vorlage `eisvogel.latex` für ansprechendes PDF-Layout
|
||
- Automatisches Ergänzen von Download-Links (`[PDF herunterladen]`) in Markdown-Dateien
|
||
- Vermeidung von doppelten Links durch Prüfung vor dem Anhängen
|
||
- Richtige Einbindung lokaler Bilder mit relativen Pfaden
|
||
- Neu bauen und Neustarten von MkDocs via Docker Compose
|
||
- Optionales Konvertieren einzelner oder mehrerer ausgewählter Markdown-Dateien
|
||
|
||
## Nutzung
|
||
````bash
|
||
Alle Markdown-Dateien in mkdocs/docs pdfen:
|
||
./mkdocs-complete.sh
|
||
|
||
Einzelne Datei konvertieren (Dateiname relativ zu `mkdocs/docs`):
|
||
./mkdocs-to-pdf.sh nextcloud-ldap.md
|
||
|
||
Mehrere Dateien gleichzeitig
|
||
./mkdocs-to-pdf.sh Einstieg_in_Linux-Desktop.md linux-als-ad-client.md
|
||
````
|
||
|
||
## Voraussetzungen
|
||
|
||
- Docker mit Zugriff auf lokale Dateien
|
||
- Docker Compose (für MkDocs Build & Restart)
|
||
- Bash als Shell Umgebung
|
||
- `pandoc/extra` Docker Image
|
||
- LaTeX Template Datei `eisvogel.latex` im Projektverzeichnis
|
||
|
||
## Verzeichnisstruktur
|
||
````
|
||
mkdocs/
|
||
├── docs/ <- Markdown Quelldateien und Medien (jetzt flach organisiert)
|
||
│ ├── nextcloud-ldap.md
|
||
│ ├── assets/
|
||
│ │ └── nextcloud/ <- Bilder und Design-Assets für Nextcloud-Seite
|
||
│ └── ... (Markdown-Dateien liegen direkt im docs-Root)
|
||
├── mkdocs.yml <- MkDocs Konfigurationsdatei
|
||
└── site/ <- Ergebnis von MkDocs Build (HTML, PDF)
|
||
````
|
||
mkdocs-to-pdf.sh <- Bash Skript zur automatischen PDF-Erstellung
|
||
eisvogel.latex <- LaTeX Vorlage für Pandoc PDF Export
|
||
docker-compose.yml <- Containerdefintionen für MkDocs Umgebung
|
||
|
||
text
|
||
|
||
## Hinweise
|
||
|
||
- Bildpfade in Markdown müssen relativ zum Markdown‑Dokument korrekt sein (z.B. `assets/nextcloud/image1.png` oder `assets/nextcloud/design/Logo.png`)
|
||
- Änderungen an Markdown führen bei Ausführung des Skripts zur Neugenerierung der PDFs
|
||
- Vor dem Commit werden automatisch PDF-Download-Links hinzugefügt, wenn noch nicht vorhanden
|
||
|
||
---
|
||
|
||
Bei Fragen oder Problemen gerne Issues öffnen oder direkt kontaktieren.
|
||
Diese README.md beschreibt übersichtlich Zweck, Nutzung, Voraussetzungen, Verzeichnisstruktur und wichtige Hinweise zum Projekt. Gerne kann sie noch projektspezifisch erweitert werden.
|
||
|
||
Für mkdocs highlighiting und so:
|
||
https://github.com/domWalters/mkdocs-to-pdf/tree/develop/docs/examples |