template-ebook/README.md

Vorlage eBook

Inhalt

• Vorlage eBook
  • Inhalt
  • Infos
  • Struktur
  • Installation und Build
    • Nötige Software für den Build
      • Schriftarten
    • Templates
      • PDF
      • eBook (epub)
      • DOCX (Office/ Word)
    • Build
      • Erklärung zum Makefile
  • Struktur beim schreiben des Buchs
  • Schreiben mit VS-Code
    • Projektinterne Tastenkombinationen mit .vscode/keybindings.json
      • Zweck
      • Einbindung in Visual Studio Code
      • 🔧 Vorgehen
      • Empfehlung
      • Hinweis zur Konsistenz
  • Nützliche Links und Tipps für den Author
  • Lizenz

---

Infos

---

Struktur

📁 .                                #
├── 📁 build                        # Ausgabeordner (wird vom Build-Prozess befüllt)
├── 📁 manuscript                   #
│   ├── 📄 00_deckblatt.md          #
│   ├── 📄 05_vorwort.md            #
│   ├── 📄 10_kapitel1.md           #
├── 📁 media                        # Bilder, Grafiken, Diagramme usw. NICHT im Manuskript enthalten sind.
│   ├── 📁 logo                     #
│   │   ├── 📄 logo.png             #
│   └── 📄 favicon.ico              #
├── 📁 metadata                     # Metadaten für eBook, Titelblatt, Author etc
│   ├── 📄 author.txt               #
│   └── 📄 ebook.yaml               #
├── 📁 styles                       # Pandoc-Templates, LaTeX-Vorlagen, CSS
│   ├── 📄 ebook-template.tex       #
│   ├── 📄 ebook.css                #
│   ├── 📄 print-template.tex       #
│   └── 📄 reference.docx           #
├── 📁 tools                        #
│   ├── 📄 bmp-emojis.md            #
│   ├── 📄 cli-emojis.md            #
│   ├── 📄 dev-setup.sh             #
│   ├── 📄 gitcopy.bat              #
│   └── 📄 tocgen.py                #
├── 📄 .gitignore                   #
├── 📄 CHANGELOG.md                 #
├── 📄 desktop.ini                  #
├── 📄 LICENSE                      # Lizenz für das Buch (z. B. CC-BY)
├── 📄 Makefile                     # Automatisierter Build-Prozess mit Pandoc etc.
├── 📄 README.md                    # Diese Datei - Erklärung zum Build des Buchs
└── 📄 VERSION                      # Paketversion (ohne Zeilenumbruch einzeilig 0.0.0)  

---

Installation und Build

Nötige Software für den Build

Hinweis: TeX unter Windows?

Obwohl es grundsätzlich möglich ist, TeX unter Windows zu installieren – und auch entsprechende Distributionen wie MiKTeX oder TeX Live für Windows existieren – rate ich dringend davon ab, auf diesem Weg zu starten.

Für einen stabilen und reproduzierbaren Build-Prozess empfiehlt sich stattdessen der Einsatz eines Linux-Systems. Wenn du kein dediziertes Linux verwendest, ist das Windows Subsystem for Linux (WSL) eine ausgezeichnete Alternative.

Voraussetzung:
Du solltest mit apt umgehen können und wissen, dass ein update vor dem install obligatorisch ist.

Falls der Build trotzdem scheitert oder du dir den Aufwand sparen möchtest, lade dir einfach die fertige PDF-Version herunter – oder bestelle dir direkt ein gedrucktes Exemplar des Buchs.

• ✅ Pandoc installieren:

  sudo apt install pandoc
  

• ✅ Empfohlene Installation: TeX Live Full (ca.8GB)

  sudo apt install texlive-full
  

  Wenn NICHT texlive-full, dann aber:

  • Zusätzlich deutsche Sprache (falls babel fehlt):

    sudo apt install texlive-lang-german
    

    Ich empfehle aber dringend texlive-full zu installieren da man erfahrungsgemäss am Anfang auf viele Fehler mit fehlenden Abhängigkeiten stößt wenn man Templates testet.

• ✅ Make installieren:

  Make oder besser die Anwendung make wird benötigt um die Erstellung der Ziele wie PDF zu automatisiern. Dafür liegt auch das vorbereitete Skript Makefile im Hauptverzeichnis. Die ist nur optional und man kann es selbstverständlich auch manuell durchführen.

  sudo apt install make
  

  Ich verwende Version:

  >  make -v
  GNU Make 4.3
  Built for x86_64-pc-linux-gnu
  

Schriftarten

sudo apt install fonts-noto-color-emoji fonts-firacode
sudo apt install fonts-symbola

Templates

PDF

eBook (epub)

DOCX (Office/ Word)

Build

Schau mal ins Makefile, dort findest Du einige Kandidaten um aus dem vorliegenden Markdown Manuskript eine entsprechende Version zu konvertieren. Es stehen zum aktuellen Zeitpunkt folgende zur Verfügung:

make pdf
make epub
make docx

Du musst im Kopfbereich der Datei zwingend ein paar Einstellungen vornehmen:

Parameter	Beschreibung
# === Allgemeine Konfiguration ===
TITLE := rust-tutorial	Dateiname ohne Erweiterung für die Ausgabe nach dem Build
MANUSCRIPT := manuscript
MANUSCRIPT := manuscript
OUTPUT := build
METADATA := metadata/ebook.yaml
CSS := styles/ebook.css
TEX_EBOOK := styles/ebook-template.tex
TEX_PRINT := styles/print-template.tex
LOGO := media/logo/logo.png	Logo für den epub Build

---

Erklärung zum Makefile

---

Struktur beim schreiben des Buchs

1. Kapitel sind in Dateien die jeweils von 00 aufsteigend sortiert sind. Pandoc baut sie aufsteigend ins Buch.
   Kapitel 1 zB in 10_kapitel1.md. Die vorstehende 10 steht für 1. Sollte zB Kapitel 1.1 hinzukommen, dann man diese 11_kapitel1.md benennen. Hoffe es ist verständlich.
2. Bilder sind nach Kapitel und fortlaufender Nummer sowie einem Hinweis benannt.

---

Schreiben mit VS-Code

Projektinterne Tastenkombinationen mit .vscode/keybindings.json

Zur Vereinfachung und Vereinheitlichung der Bedienung ist in diesem Projekt eine Datei .vscode/keybindings.json enthalten. Diese Datei definiert projektweit gültige Tastenkombinationen, die bestimmte Aufgaben in Visual Studio Code auslösen – beispielsweise den PDF-Build aus Markdown heraus.

⚠ Diese Datei ist verpflichtender Bestandteil des Projekts und muss bei jeder lokalen Arbeitskopie vorhanden sein.

---

Zweck

Die keybindings.json im Projektordner ermöglicht es, projektbezogene Aktionen wie das Erzeugen von PDF-Dokumenten über eine einfache Tastenkombination aufzurufen. Sie ergänzt die zentrale Datei tasks.json, in der die ausführbaren Aktionen definiert sind.

Ein typischer Anwendungsfall ist die Kombination mit einem WSL-basierten Build-Befehl:

{
  "key": "ctrl+alt+p",
  "command": "workbench.action.tasks.runTask",
  "args": "Markdown → PDF (Pandoc via WSL)",
  "when": "editorLangId == markdown"
}

Diese Tastenkombination führt den Build-Task Markdown → PDF (Pandoc via WSL) aus, der wiederum intern wsl make pdf ausführt.

Einbindung in Visual Studio Code

Visual Studio Code erlaubt von Haus aus keine automatische Nutzung Projektinterne keybindings.json-Dateien. Daher muss der Inhalt aus .vscode/keybindings.json manuell in das globale Benutzerprofil übernommen werden:

🔧 Vorgehen

1. Öffne in VS Code die Tastenkombination Strg + Shift + P
2. Wähle: Preferences: Open Keyboard Shortcuts (JSON)
3. Kopiere den Inhalt aus der Datei .vscode/keybindings.json ins geöffnete Profil
4. Speichern, fertig

💬 Alternativ kann die Datei bei einer Neuinstallation auch einfach in den globalen Pfad kopiert werden. Unter Windows befindet sich dieser unter %APPDATA%\Code\User\keybindings.json.

Empfehlung

Es wird empfohlen, regelmäßig zu prüfen, ob die Projektinterne keybindings.json aktualisiert wurde (z. B. durch einen Pull). Neue Funktionen oder Workflows können dort neue Tastenkombinationen erhalten.

Hinweis zur Konsistenz

Um eine konsistente Bedienbarkeit zu gewährleisten, sollte ausschließlich die im Projekt enthaltene keybindings.json verwendet werden. Eigene globale Kürzel sollten nach Möglichkeit vermieden oder dokumentiert angepasst werden.

---

Nützliche Links und Tipps für den Author

• Zeichen Testen -> https://r12a.github.io/uniview/

Oder hexdump aus:

sudo apt install bsdmainutils

---

Lizenz

(C) 2025 - Adam Skotarczak

---