# WYSIWYG Editor — Manual

> Vollständige Funktionsbeschreibung des WYSIWYG-Editors: jede Toolbar-Funktion, alle TipTap-Extensions, Import/Export-Formate, Architektur und Grenzen.

Source: https://www.jpkc.com/db/tools/wysiwyg/manual/

Zurück zur Übersicht: [WYSIWYG Editor](https://www.jpkc.com/db/tools/wysiwyg/) · Tool live öffnen: [www.jpkc.com/tools/wysiwyg/](https://www.jpkc.com/tools/wysiwyg/)

Dieses Manual beschreibt den **WYSIWYG Editor** vollständig: jede Toolbar-Funktion, die zugrunde liegenden TipTap-Extensions, alle Import- und Export-Formate, die Architektur und die technischen Grenzen. Die Oberfläche des Tools ist auf Englisch — die Button- und Menü-Bezeichnungen werden hier deshalb in ihrer englischen Original-Schreibweise genannt (mit deutscher Erläuterung), damit du dich im echten Interface zurechtfindest.

## Grundkonzept

Der Editor ist eine **einzige formatierte Schreibfläche** (kein geteiltes Quelltext-Fenster). Du tippst Text, formatierst ihn über die Toolbar oder Tastenkürzel, und der Editor pflegt darunter ein sauberes Dokumentmodell. Technisch ist es [TipTap 3](https://tiptap.dev/) — ein headless Rich-Text-Framework auf Basis von ProseMirror — gebündelt zu einer fertigen Anwendung. Über der Schreibfläche liegt eine zweizeilige Toolbar, darunter eine Statusleiste mit Dokument-Kennzahlen.

Beim ersten Tippen helfen **Live-Markdown-Eingaberegeln** (über das TipTap-StarterKit): `# ` am Zeilenanfang macht eine Überschrift, `- ` eine Aufzählung, `1. ` eine Nummerierung, `> ` ein Zitat, ` ``` ` einen Code-Block, `**fett**` und `*kursiv*` setzen Marken. Der Platzhalter im leeren Editor weist darauf hin: „Start writing… (type ‚# ' for a heading, ‚- ' for a list)".

## Die Toolbar, Zeile 1 — Datei, Verlauf, Formate, Ansicht

### File operations (Dateioperationen)

Vier Buttons für den Dokument-Ein- und -Ausgang auf Dateiebene:

- **Open local HTML file** — öffnet eine lokale `.html`-/`.htm`-/`.txt`-Datei und lädt ihren Inhalt in den Editor (ersetzt den aktuellen Inhalt).
- **Save as HTML file** — speichert den aktuellen Inhalt als **eigenständige, hell gestaltete HTML-Datei** (`document.html`) mit eingebettetem Stylesheet, sodass das Ergebnis auf weißem Grund lesbar ist, unabhängig vom Editor-Theme. Code wird statisch syntaxbeleuchtet, Formeln mit KaTeX gerendert, ausklappbare Abschnitte aufgeklappt.
- **Insert HTML from URL** — öffnet einen Dialog, in den du eine absolute http(s)-Adresse einträgst; das HTML dieser Seite wird über den serverseitigen Proxy abgerufen und in den Editor geladen (siehe [Architektur](#architektur-und-datenschutz)).
- **Clear editor content** — leert den Editor nach Rückfrage und löscht den lokalen Speicher.

### Clipboard und History

- **Cut / Copy / Paste** (`Strg+X` / `Strg+C` / `Strg+V`) — Ausschneiden, Kopieren, Einfügen. Innerhalb des Editors bleibt beim Einfügen der genaue Inline-/Block-Kontext erhalten; externer Inhalt wird bevorzugt als Rich-HTML, sonst als Klartext übernommen.
- **Undo / Redo** (`Strg+Z` / `Strg+Y`) — Rückgängig und Wiederherstellen über die TipTap-History.

### Markdown (Import / Export)

- **Import** — öffnet den Markdown-Import-Dialog: Markdown einfügen, eine `.md`-Datei laden oder Markdown von einer URL holen. Bestätigen ersetzt den Editor-Inhalt.
- **Export** — wandelt den aktuellen Inhalt in Markdown um und zeigt ihn in einem Dialog, von dort kopierbar oder als `document.md` speicherbar.

Details zum Round-Trip stehen unter [Markdown-Verarbeitung](#markdown-import-und-export).

### JSON (Import / Export)

- **Import** — lädt ein **TipTap-/ProseMirror-Dokument als JSON** (eingefügt oder als `.json`-Datei). Das ist das native, **verlustfreie** Dokumentmodell des Editors — aber nur für genau diesen Editor sinnvoll, weil es vom Knoten-Schema abhängt. Ungültiges oder fremdes JSON wird abgewiesen und der vorherige Inhalt wiederhergestellt (Fehlermeldung statt geleertem Editor).
- **Export** — gibt das aktuelle Dokument als formatiertes JSON aus (kopierbar oder als `document.json` speicherbar).

### Editor theme (Editor-Thema)

Drei Schreibflächen-Themes: **Dark**, **Light**, **Sepia**. Die Wahl wird im Browser gemerkt. Wichtig: Das ist nur die Optik der Schreibfläche — **Vorschau, Druck, HTML- und PDF-Export sind immer hell gestaltet**, damit das Ergebnis überall lesbar ist.

### Find / Replace (Suchen / Ersetzen)

- **Find** (`Strg+F`) und **Find & Replace** (`Strg+H`) öffnen eine Suchleiste über der Schreibfläche. Sie nutzt `prosemirror-search` und hebt alle Treffer hervor.
- Optionen: **Case** (Groß-/Kleinschreibung beachten), **Word** (nur ganze Wörter), **Regex** (Regulärer Ausdruck). Mit **Replace** / **Replace all** ersetzt du den aktuellen bzw. alle Treffer. `Enter` springt zum nächsten Treffer, `Shift+Enter` zum vorherigen, `Esc` schließt.

### Preview / view (Vorschau und Ansicht)

- **Show invisible characters** — blendet unsichtbare Zeichen (Leerzeichen, Umbrüche) ein und aus.
- **Table of contents** — öffnet ein seitliches Inhaltsverzeichnis aus allen Überschriften; ein Klick springt zur Stelle.
- **Preview (Light)** — zeigt den Inhalt schreibgeschützt und hell gerendert in einem Dialog (mit eigenen Buttons zum Speichern als HTML, Drucken und PDF).
- **Print (Light)** — öffnet ein hell gestaltetes Druckfenster.
- **Save as PDF** — erzeugt ein PDF (`document.pdf`) über html2pdf (html2canvas + jsPDF).
- **Toggle fullscreen** — Vollbild-/ablenkungsfreier Modus; `Esc` verlässt ihn.

## Die Toolbar, Zeile 2 — Formatierung

### Block type (Blocktyp)

Ein Aufklappmenü, das den aktuellen Block umschaltet: **Paragraph**, **Heading 1**–**Heading 6**, **Code block**, **Quote**. Das Label zeigt jeweils den aktiven Blocktyp.

### Code language (Code-Sprache)

Setzt die Syntax-Highlighting-Sprache des aktuellen Code-Blocks (oder erzeugt einen, wenn der Cursor in keinem ist). Auswahl: **Plain text** plus 17 Sprachen — HTML/XML, CSS, JavaScript, PHP, Python, Java, C, C++, C#, Ruby, Go, Rust, SQL, Bash, JSON, YAML, Markdown. Die Hervorhebung leistet `lowlight` mit der highlight.js-Engine (siehe [Syntax-Highlighting](#syntax-highlighting)).

### Font family (Schriftart)

Setzt die Schriftart der Auswahl: **Default font** plus neun Stacks (Arial, Times New Roman, Georgia, Courier New, Verdana, Trebuchet MS, Tahoma, Comic Sans MS, Monospace).

### Inline marks (Textauszeichnung)

Die Inline-Marken: **Bold** (`Strg+B`), **Italic** (`Strg+I`), **Underline** (`Strg+U`), **Strikethrough**, **Inline code**, **Subscript** (tief), **Superscript** (hoch). Aktive Marken werden in der Toolbar hervorgehoben.

### Color & highlight (Farbe und Hervorhebung)

- **Apply text color** — wendet die zuletzt gewählte Textfarbe an; ein Farbwähler-Feld daneben lässt eine neue Farbe wählen.
- **Highlight** — Textmarker-Hervorhebung (mehrfarbig möglich).
- **Clear formatting** — entfernt alle Marken und setzt Blöcke zurück.

### Lists (Listen)

**Bullet list** (Aufzählung), **Numbered list** (Nummerierung), **Task list** (Aufgabenliste mit Checkboxen, verschachtelbar).

### Alignment (Ausrichtung)

**Align left / center / right** und **Justify** (Blocksatz) für Überschriften und Absätze.

### Insert (Einfügen)

- **Add link** / **Remove link** — Link auf die Auswahl setzen bzw. entfernen (Auto-Verlinkung und Verlinkung beim Einfügen sind aktiv; Links öffnen im Editor nicht beim Klick).
- **Insert image** — Aufklappmenü: **From URL** (Bild-URL eingeben) oder **Upload (base64)** (lokale Datei als eingebettetes base64-Bild). Bilder lassen sich auch per Drag-and-drop in den Editor ziehen.
- **Table** — **Insert table** (3×3 mit Kopfzeile) plus Operationen: Spalte/Zeile davor/danach einfügen, Spalte/Zeile löschen, **Toggle header row**, **Merge / split cells**, **Delete table**. Tabellen sind in der Breite anpassbar.
- **Horizontal rule** — waagerechte Trennlinie.
- **Collapsible section** — ein ausklappbarer `<details>`-Abschnitt mit Titel und Inhalt.
- **Math (KaTeX)** — **Inline math ($…$)** oder **Block math ($$…$$)**; nach LaTeX gefragt, mit KaTeX gerendert. Ein Klick auf eine gerenderte Formel öffnet sie zum Bearbeiten.
- **Emoji** — durchsuchbarer Emoji-Picker. Alternativ im Text `:` tippen für die Shortcode-Autovervollständigung.

### Bubble menu und Drag-Handle

Bei markiertem Text erscheint eine **Auswahl-Blase** mit Bold, Italic, Underline, Strikethrough, Inline code und Add link. Fährst du über einen Block, zeigt sich links ein **Drag-Handle** zum Verschieben des Blocks.

## Die Extensions im Überblick

Der Editor bündelt diese TipTap-Extensions (faktische Liste aus dem Bundle):

- **StarterKit** — Basis-Knoten und -Marken: Absatz, Überschriften (H1–H6), fett, kursiv, durchgestrichen, Inline-Code, Zitat, Aufzählungs-/Nummerierungslisten, waagerechte Linie, Hard-Break, History (Undo/Redo) und die Markdown-Eingaberegeln. (Der eingebaute Link und Code-Block sind deaktiviert und durch die spezialisierten Versionen ersetzt.)
- **Link** — eigenständig konfiguriert (Auto-Link, Link beim Einfügen, kein Öffnen per Klick im Editor).
- **CodeBlockLowlight** — Code-Blöcke mit Syntax-Highlighting.
- **TextStyle, Color, FontFamily** — Textfarbe und Schriftart.
- **Highlight** (mehrfarbig), **Subscript**, **Superscript**.
- **TextAlign** — Ausrichtung für Überschriften und Absätze.
- **TaskList / TaskItem** — Aufgabenlisten (verschachtelbar).
- **Table / TableRow / TableHeader / TableCell** — Tabellen (in der Breite anpassbar).
- **Image** — Bilder, base64 erlaubt.
- **Details / DetailsSummary / DetailsContent** — ausklappbare Abschnitte.
- **Typography** — typografische Ersetzungen (z. B. Anführungszeichen, Gedankenstriche).
- **Mathematics** — KaTeX-Formeln, inline und als Block.
- **CharacterCount** — Wort- und Zeichenzählung (für die Statusleiste).
- **InvisibleCharacters** — unsichtbare Zeichen anzeigen.
- **FileHandler** — Drag-and-drop von Bildern (als base64) sowie von HTML-/Markdown-Dateien (öffnen als neues Dokument).
- **Placeholder** — Platzhaltertext im leeren Editor.
- **Emoji** — Emoji-Knoten mit `:shortcode:`-Autovervollständigung.
- **TableOfContents** — Inhaltsverzeichnis aus den Überschriften.
- **prosemirror-search** — Suchen und Ersetzen.
- **BubbleMenu** — die Auswahl-Blase.
- **DragHandle** — der Block-Verschiebegriff.

## Markdown-Import und -Export

Markdown wird über einen **HTML-Round-Trip** verarbeitet, der die etablierten Bibliotheken des Projekts nutzt:

- **Import (Markdown → HTML):** [markdown-it](https://github.com/markdown-it/markdown-it) mit aktivem `linkify` und HTML-Durchlass, plus Plugins für Aufgabenlisten, Tiefstellung (`~x~`), Hochstellung (`^x^`) und Hervorhebung (`==x==`). YAML-Frontmatter am Dokumentanfang wird in einen `yaml`-Code-Block umgewandelt, statt zerschossen zu werden. LaTeX-Mathematik (`$…$` / `$$…$$`) wird erkannt und als Formel-Knoten eingesetzt; `$`-Zeichen in Code-Blöcken werden geschützt.
- **Export (HTML → Markdown):** [Turndown](https://github.com/mixmark-io/turndown) mit der GitHub-Flavored-Markdown-Erweiterung (Tabellen, Aufgabenlisten, Durchstreichung). Überschriften im ATX-Stil (`#`), Aufzählungen mit `-`, Code-Blöcke gefenced. Eigene Regeln halten Überschriften und Links einzeilig und übersetzen Tief-/Hochstellung zurück nach `~x~` / `^x^` sowie Formeln nach `$…$` / `$$…$$`.

### Grenzen des Markdown-Round-Trips

- **SVG-Bilder als `data:`-URL überleben den Markdown-Round-Trip nicht** (bewusst aus Sicherheitsgründen, weil ein Link auf ein SVG dessen Skripte ausführen könnte). Über den HTML-Round-Trip funktionieren sie. Raster-Bilder (PNG, JPEG, GIF, WebP …) als base64 bleiben erhalten.
- **Highlight (`==x==`)** wird beim **Import** erkannt; beim Export nach Markdown gibt es dafür keine Regel — eine Hervorhebung wird beim Markdown-Export also zu normalem Text. (Im HTML- und JSON-Export bleibt sie erhalten.)
- Markdown hat keine native Syntax für Tief-/Hochstellung — dafür kommen die `~x~`/`^x^`-Konventionen zum Einsatz, die nicht jeder Markdown-Renderer versteht.

## Syntax-Highlighting

Code-Blöcke werden farblich hervorgehoben — über **`lowlight`**, das die **highlight.js**-Engine kapselt. Im laufenden Editor zeichnet TipTap die Farben über ProseMirror-Dekorationen (nur für die Ansicht). Weil diese Dekorationen **nicht** im serialisierten HTML landen, beleuchtet das Tool für Vorschau, Druck und Export die Code-Blöcke zusätzlich **statisch** mit highlight.js neu. Der registrierte Sprachsatz umfasst die 17 oben genannten Sprachen; die Sprache eines Blocks wählst du über das **Code language**-Menü.

## Statusleiste und Auto-Speicherung

Unter der Schreibfläche zeigt eine Statusleiste die Dokument-Kennzahlen im Format **„HTML: N bytes | N words | N blocks | ~N min read"** (Bytes des HTML, Wortzahl, Block-Anzahl, geschätzte Lesezeit bei ~200 Wörtern/Minute).

Der Inhalt wird **automatisch im lokalen Browser-Speicher** gesichert (verzögert nach Eingaben). Beim nächsten Öffnen stellt der Editor ihn wieder her. Es gibt **einen** Speicherplatz (ein Dokument); **Clear editor content** löscht ihn. Das Speicher-Badge oben rechts zeigt den Status an.

## Architektur und Datenschutz

Der Editor läuft **fast vollständig clientseitig**:

- **Im Browser:** das gesamte Bearbeiten, der Markdown-, JSON- und HTML-Export, der PDF-Export, die Vorschau und der Druck sowie die Auto-Speicherung. Dein Inhalt wird **nur im lokalen Browser-Speicher** gehalten und nie auf einen Server hochgeladen.
- **Serverseitig — nur der URL-Abruf:** Die Funktionen **Insert HTML from URL** und **Load from URL** (im Markdown-Import) holen die fremde Seite über einen **serverseitigen JPKCom-Proxy**, weil der Browser fremde Seiten wegen CORS nicht direkt laden darf. Die Zielseite sieht damit einen Request vom JPKCom-Server (mit dessen User-Agent), **nicht deine IP-Adresse**.

Die beiden serverseitigen Endpunkte (ein Fetch-Proxy und ein token-basierter Authentifizierungs-Endpunkt) sind **kein öffentliches API**, das du selbst aufrufen kannst — sie werden ausschließlich vom JavaScript des Tools genutzt und sind gegen Missbrauch gehärtet:

- **Token-Authentifizierung:** Vor jedem Abruf holt das Tool ein frisches, täglich rotierendes Zwei-Faktor-Token (SHA-256); der Token-Endpunkt prüft Referer und ein tägliches API-Secret.
- **SSRF-Schutz:** private, lokale und interne IP-Adressen werden blockiert; nur HTTP/HTTPS.
- **Grenzen:** maximale Antwortgröße **950 KB**, Timeout **10 s**, maximale Ausführungszeit **20 s**.

Optional gibt es einen **Expert Mode** mit einem lokalen Proxy (`http://127.0.0.1:<port>`): Statt über den JPKCom-Server holt dann ein selbst betriebener lokaler Proxy die Seite. Die Einrichtung ist fortgeschritten und für den normalen Betrieb nicht nötig.

## Betriebsgrenzen — kompakt

- **Ein Dokument, ein Speicherplatz.** Keine Mehrfach-Dokumente, keine Kollaboration. Browserdaten löschen heißt Inhalt verlieren — vorher als Datei exportieren.
- **base64-Bilder blähen auf.** Per Upload eingebettete Bilder landen als base64 direkt im HTML und im lokalen Speicher; viele oder große Bilder können das Dokument groß machen und das Speicher-Kontingent sprengen. Bilder vorher verkleinern (siehe [Tipps](https://www.jpkc.com/db/tools/wysiwyg/tips/)).
- **JSON nur aus diesem Editor.** Der JSON-Import ist nur für JSON gedacht, das dieser Editor exportiert hat; fremdes JSON wird abgewiesen.
- **URL-Abruf:** nur öffentliche http(s)-Adressen, max. 950 KB, kein localhost/Intranet.
- **Emojis:** nur solche mit nativem Unicode-Zeichen (bis Unicode 15); neuere oder reine Bild-Emojis sind aus Darstellungs- und Datenschutzgründen entfernt.

Für den Einstieg und die Zielgruppen siehe die [Übersichtsseite](https://www.jpkc.com/db/tools/wysiwyg/), für Arbeitsabläufe die [Beispiele](https://www.jpkc.com/db/tools/wysiwyg/examples/) und für Kniffe die [Tipps & Tricks](https://www.jpkc.com/db/tools/wysiwyg/tips/). Ausprobieren kannst du alles direkt im [Tool](https://www.jpkc.com/tools/wysiwyg/).