claude-plugins/doc-converter/skills/doc-converter-expert/SKILL.md

name, description

name	description
doc-converter-expert	Expert guidance for DOCX/PDF to HTML conversion using the doc-converter service. Use when converting documents, diagnosing conversion issues, understanding layout templates (Vorlagen), or working with the Gemini Vision API for document analysis.

Document Converter Expert

Expert guidance for converting DOCX/PDF documents to Jodit-compatible HTML using the doc-converter service.

---

Overview

The doc-converter service uses Gemini Vision to analyze document images and generate HTML that matches the visual layout. Documents are classified into three types:

Type	Detection	Approach
Standard	Blue headers (#B8CCE4), table-based sections	Follow Standard template rules - NUR Vorlagen-Farben!
Verfahrensanweisung (VA)	Rosa headers (#E6B8B7/#F2DCDB), h2-based with procedure table	Follow VA template rules - NUR Vorlagen-Farben!
Other	No template match	1:1 EXAKT wie im Dokument - alle Farben/Strukturen übernehmen

---

KRITISCHE REGELN für VA und Standard

Erlaubte Farben - NUR DIESE!

Standard (Blau):

Element	Farbe	Hex
Header-Zeile	Blau	#B8CCE4
Nummerierungsspalte	Blau (gleich wie Header!)	#B8CCE4
Datenzellen	Weiß/transparent	-

Verfahrensanweisung (Rosa):

Element	Farbe	Hex
Header-Zeile	Rosa	#E6B8B7
Nummerierungsspalte	Rosa (IDENTISCH wie Header!)	#E6B8B7
Datenzellen	Weiß/transparent	-

KRITISCH: Header und Nummerierungsspalte MÜSSEN denselben Hex-Code haben!

VERBOTEN bei VA/Standard Verfahrenstabellen:

• Unterschiedliche Farben zwischen Header und Nummerierungsspalte
• Hintergrundfarbe auf normalen Datenzellen (außer Nummerierungsspalte)

ERLAUBT bei anderen Tabellen im Dokument (z.B. Legende):

• Alle Farben 1:1 wie im Original: gelb, grün, rot, grau etc.

Dokument-Header und Titel Behandlung

Der Dokumenttitel MUSS im Content erscheinen!

• Die Hauptüberschrift (Dokumenttitel) → wird als <h1> GANZ OBEN im content_html eingefügt
• Format: <h1 style="font-size: 14pt; font-weight: bold; margin: 0 0 10px 0; font-family: Arial, sans-serif; text-align: center;">Dokumenttitel</h1>
• Danach folgt der restliche Content ab Sektion 1

KEINE Logos oder Bilder aus dem Header-Bereich!

• Logos (Firmenlogos, Wappen) die im Kopfbereich erscheinen: IGNORIEREN!
• Diese werden automatisch vom System herausgefiltert (Hash-basierte Duplikat-Erkennung)
• Referenziere NUR inhaltliche Bilder (Diagramme, Fotos) — KEINE Header-Logos!

RICHTIG:  "Verfahrensanweisung Dienstplan" → als <h1> im content_html
RICHTIG:  Diagramm aus Dokument → <img src="content_1.png">
FALSCH:   Logo-Bild extrahieren und referenzieren
FALSCH:   Logo mehrfach im HTML anzeigen

TOC (Inhaltsverzeichnis) — NIEMALS im Content!

ABSOLUTE REGEL: Das TOC gehört NICHT in content_html!

• Das Inhaltsverzeichnis wird SEPARAT in toc_html ausgegeben
• Wenn das Originaldokument ein TOC hat: ÜBERSPRINGEN im Content!
• Der Content beginnt DIREKT mit dem Dokumenttitel (<h1>) und dann Sektion 1
• VERBOTEN: Klickbare Links wie "1. Zweck", "2. Geltungsbereich" im Content!

Pipeline-Architektur (3-Phasen-Hybrid)

PDF → pdftoppm → Seitenbilder
  Phase 1: recognize_document_structure() (Gemini, 3 Content-Seiten)
    → header_bottom_pct, footer_top_pct (Crop-Koordinaten)
  crop_page_images() → gecroppte Seitenbilder (Header/Footer entfernt)
  Phase 2a: TOC + Footer generieren
  Phase 2b: Content pro Seite (gecroppte Bilder, KEINE Header/Footer-Referenz)
  Post-Processing: normalize_content_structure() → normalize_font_sizes()

TOC-Sektion-1-Fix

Wenn "1. Inhaltsverzeichnis" die erste Sektion im TOC ist:

• Die Funktion fix_toc_section_one() korrigiert automatisch
• Fall 1: "1. Inhaltsverzeichnis" → wird ersetzt mit "1. "
• Fall 2: TOC beginnt bei "2." → "1. " wird hinzugefügt
• Die h1-Überschrift bekommt id="sec-1" und das "1." Präfix

TOC Format mit HÄNGENDEM EINZUG (h2, h3, h4):

⚠️ KRITISCH: Hängender Einzug bei Zeilenumbruch! Bei langen Titeln die umbrechen, MUSS der Text unter dem ERSTEN WORT weitergehen, NICHT am linken Rand!

FALSCH:                              RICHTIG:
4.1.1 Externe Signatur Servicehaus   4.1.1 Externe Signatur Servicehaus
Sonnenhalde  ← am Rand!                    Sonnenhalde  ← unter "Externe"!

Technik: padding-left + negativer text-indent:

<!-- Level 1: h2 (1., 2., 3.) -->
<div class="toc-entry toc-level-1" style="line-height: 1.5; padding-left: 20px; text-indent: -20px;"><a href="#sec-1">1. Zweck der Verfahrensanweisung</a></div>

<!-- Level 2: h3 (3.1., 4.2.) - zusätzlich margin-left: 15px -->
<div class="toc-entry toc-level-2" style="line-height: 1.5; margin-left: 15px; padding-left: 32px; text-indent: -32px;"><a href="#sec-3-1">3.1. Grundlagen</a></div>

<!-- Level 3: h4 (4.1.1., 4.3.2.) - zusätzlich margin-left: 30px -->
<div class="toc-entry toc-level-3" style="line-height: 1.5; margin-left: 30px; padding-left: 44px; text-indent: -44px;"><a href="#sec-4-1-1">4.1.1. Externe Signatur Servicehaus Sonnenhalde</a></div>

WICHTIG: h3 UND h4 Überschriften MÜSSEN im TOC erscheinen!

Hierarchische Einrückung — GENERELLE REGEL!

Alles was einem übergeordneten Element untersteht, wird eingerückt!

• Einrückung erfolgt über margin-left in 20px-Schritten
• Ebene 1 (h2): margin-left: 0
• Ebene 2 (h3, Listen unter h2): margin-left: 20px
• Ebene 3 (Listen unter h3, verschachtelte Listen): margin-left: 40px
• usw.

Tabellen und Bilder — MIT Einrückung und Abstand:

• Tabellen: margin-left entsprechend der Hierarchie-Ebene + Abstand oben/unten!
  • Tabelle unter h2: margin: 15px 0 15px 20px;
  • Tabelle unter h3: margin: 15px 0 15px 40px;
  • Ausnahme: Verfahrenstabelle (Sektion 4) mit width: 100% hat margin-left: 0
• Bilder: Eingerückt + Abstand! ALLE Bilder aus dem Original müssen erscheinen!

Tabellen — Einrückung statt Zentrierung

Tabellen werden eingerückt (nicht zentriert):

<table border="1" style="border-collapse: collapse; margin: 15px 0 15px 20px; font-family: Arial, sans-serif; font-size: 11pt;">

Ausnahme: Verfahrenstabellen (Sektion 4) mit 4 Spalten: width: 100%; margin-left: 0;

h2 für Hauptsektionen (1., 2., 3.):

<h2 id="sec-1" style="font-size: 12pt; font-weight: bold; margin: 10px 0 5px 0; font-family: Arial, sans-serif;">1. Zweck</h2>

h3 für Untersektionen (3.1., 3.2.):

<h3 id="sec-3.1" style="font-size: 11pt; font-weight: bold; margin: 10px 0 5px 20px; font-family: Arial, sans-serif;">3.1. Grundlagen</h3>

Absätze unter h3:

<p style="margin: 0 0 5px 20px; line-height: 1.5; font-family: Arial, sans-serif; font-size: 11pt;">Text</p>

Listen — Einrückung je nach Hierarchie-Ebene — KRITISCH!

⚠️ VERBOTEN: Listen die am linken Rand beginnen wenn sie unter h3 stehen! ⚠️

Listen unter h2 (Ebene 2): margin-left: 25px Listen unter h3 (Ebene 3): margin-left: 45px — PFLICHT!

VISUELLES ZIEL: Die Bullet-Points MÜSSEN weiter rechts beginnen als der erste Buchstabe der h3-Überschrift!

FALSCH (VERBOTEN!):

3.1. Grundlagen
• Bullet am linken Rand     ← FALSCH! Keine Einrückung!

RICHTIG:

3.1. Grundlagen
    • Bullet eingerückt     ← RICHTIG! Bullet beginnt weiter rechts

HTML-CODE für VA — Liste unter h3:

<h3 id="sec-3.1" style="font-size: 11pt; font-weight: bold; margin: 10px 0 5px 20px; font-family: Arial, sans-serif;">3.1. Grundlagen</h3>
<ul style="list-style-type: disc; margin: 5px 0 5px 45px; padding-left: 0;">
  <li style="line-height: 1.5; font-family: Arial, sans-serif; font-size: 11pt;">Betriebsmedizinliste ist eine vorgegebene...</li>
</ul>

KRITISCH: margin-left: 45px auf der <ul> — NICHT 25px, NICHT 0!

Verschachtelte Listen (Listen in Listen): zusätzliche 20px

<ul style="...margin-left: 25px...">
  <li>Hauptpunkt
    <ul style="...margin-left: 20px...">
      <li>Unterpunkt (nochmal eingerückt)</li>
    </ul>
  </li>
</ul>

Hängender Einzug: Bei Zeilenumbruch Text bündig mit erstem Wort, NICHT mit Bullet!

Farbige Hinweisfelder INNERHALB von Listenpunkten

Wenn ein gelbes/farbiges Hinweisfeld zum Text eines Listenpunkts gehört:

• Das Feld ist TEIL des <li>, NICHT ein separates Element!
• Verwende display: inline-block; damit es NICHT volle Breite hat
• Die Originalfarbe übernehmen (gelb = #FFFF00 oder #FFF2CC, NICHT rosa!)

<li style="...">
  Text des Listenpunkts der vor dem Hinweis steht
  <div style="background-color: #FFFF00; padding: 5px; margin-top: 5px; display: inline-block;">
    Passwort für jeden Standort: SHS-MalBm
  </div>
</li>

FALSCH: Hinweisfeld als separates <div> mit voller Breite außerhalb der Liste!

Footer-Tabelle Styling

Die Footer-Tabelle hat 4 Spalten, NUR die Header-Zeile mit Hintergrundfarbe, und verwendet 8pt (kleiner als Content-Text):

<table style="width: 100%; border-collapse: collapse; border: none; font-family: Arial, sans-serif; font-size: 8pt;">
  <tr>
    <td style="width: 25%; background-color: #E6B8B7; padding: 4px; vertical-align: top; border: none;">
      <p style="margin: 0; line-height: 1.5; font-size: 8pt;">Freigabe</p>
    </td>
    <td style="width: 25%; background-color: #E6B8B7; padding: 4px; vertical-align: top; border: none;">
      <p style="margin: 0; line-height: 1.5; font-size: 8pt;">Bearbeiter</p>
    </td>
    <td style="width: 25%; background-color: #E6B8B7; padding: 4px; vertical-align: top; border: none;">
      <p style="margin: 0; line-height: 1.5; font-size: 8pt;">Änderungsstand</p>
    </td>
    <td style="width: 25%; background-color: #E6B8B7; padding: 4px; vertical-align: top; border: none;">
      <p style="margin: 0; line-height: 1.5; font-size: 8pt;">Datum</p>
    </td>
  </tr>
  <tr>
    <td style="width: 25%; padding: 4px; vertical-align: top; border: none;">
      <p style="margin: 0; line-height: 1.5; font-size: 8pt;">QM</p>
    </td>
    <td style="width: 25%; padding: 4px; vertical-align: top; border: none;">
      <p style="margin: 0; line-height: 1.5; font-size: 8pt;">Name</p>
    </td>
    <td style="width: 25%; padding: 4px; vertical-align: top; border: none;">
      <p style="margin: 0; line-height: 1.5; font-size: 8pt;">1.0</p>
    </td>
    <td style="width: 25%; padding: 4px; vertical-align: top; border: none;">
      <p style="margin: 0; line-height: 1.5; font-size: 8pt;">01.01.2025</p>
    </td>
  </tr>
</table>

WICHTIG: 4 Spalten: Freigabe, Bearbeiter, Änderungsstand, Datum. KEINE "Seite"-Spalte! Beachte: Datenzellen haben KEINE Hintergrundfarbe, nur die Header-Zeile!

Tabellen durch Bilder unterbrochen — Header wiederholen!

Wenn eine Tabelle durch ein Bild unterbrochen wird, MUSS die Header-Zeile nach dem Bild wiederholt werden!

<table border="1" style="...">
  <tr>
    <th colspan="2" style="...background-color: #E6B8B7;">Aufgabe</th>
    <th style="...background-color: #E6B8B7;">Verantwortung</th>
    <th style="...background-color: #E6B8B7;">Mittel</th>
  </tr>
  <tr>
    <td style="...background-color: #F2DCDB;">1</td>
    <td>Schritt 1a</td>
    <td>MA</td>
    <td>Telefon</td>
  </tr>
  <tr>
    <td style="...background-color: #F2DCDB;">1b</td>
    <td>Schritt 1b</td>
    <td>BL</td>
    <td>-</td>
  </tr>
</table>

<!-- BILD unterbricht die Tabelle - MIT Einrückung und Abstand! -->
<div style="text-align: center; margin: 15px 0 15px 20px;"><img src="content_1.png" alt="Vorsorgekartei" style="max-width: 100%;"></div>

<!-- NEUE Tabelle mit WIEDERHOLTER Header-Zeile! -->
<table border="1" style="...">
  <tr>
    <th colspan="2" style="...background-color: #E6B8B7;">Aufgabe</th>
    <th style="...background-color: #E6B8B7;">Verantwortung</th>
    <th style="...background-color: #E6B8B7;">Mittel</th>
  </tr>
  <tr>
    <td style="...background-color: #F2DCDB;">2</td>
    <td>Schritt 2a</td>
    <td>MA</td>
    <td>Formular</td>
  </tr>
</table>

WICHTIG: Nach jedem unterbrechenden Bild beginnt eine NEUE Tabelle mit vollständiger Header-Zeile!

Nummerierungsspalte = Header-Farbe

PFLICHT: Die Nummerierungsspalte (1, 2, 3...) MUSS EXAKT die gleiche Hintergrundfarbe haben wie die Header-Zeile der Tabelle!

<!-- VA: Rosa Header → Rosa Nummerierung -->
<tr>
  <th style="...background-color: #E6B8B7;">Aufgabe</th>
  ...
</tr>
<tr>
  <td style="...background-color: #F2DCDB; text-align: center;">1</td>
  <td style="...">Beschreibung (KEIN Hintergrund!)</td>
  ...
</tr>

<!-- Standard: Blau Header → Blau Nummerierung -->
<tr>
  <th style="...background-color: #B8CCE4;">3. Durchführung</th>
  ...
</tr>
<tr>
  <td style="...background-color: #B8CCE4; text-align: center;">1</td>
  <td style="...">Beschreibung (KEIN Hintergrund!)</td>
  ...
</tr>

---

Layout-Vorgaben für Dokumente MIT TOC (Abweichungen von 1:1)

Dokumente die ein Inhaltsverzeichnis haben (Standard/VA) bekommen folgende Anpassungen, die von einer 1:1-Darstellung des Originals abweichen:

1. TOC wird NEU generiert (nicht aus dem Original)

• Original-TOC (Punktreihen, Seitenzahlen) wird komplett verworfen
• Phase 2a extrahiert TOC-Einträge als JSON, generate_toc_from_entries() erzeugt festes Template
• Format: <div class="toc-entry toc-level-N"> mit <a href="#sec-N">
• Seitenzahlen und Punktreihen werden entfernt

2. TOC-Seiten und Titelseite werden im Content übersprungen

• Alle Pre-Content-Seiten (Titel, TOC) werden NICHT an Gemini zur Content-Konvertierung gesendet
• Content beginnt bei first_content_page (aus Phase 1)

3. "1. Inhaltsverzeichnis" → Dokumenttitel

• fix_toc_section_one() ersetzt "1. Inhaltsverzeichnis" mit "1. "
• Oder fügt "1. " hinzu wenn TOC bei "2." beginnt

4. Dokumenttitel wird als h1 nachträglich eingefügt

• h1 mit 16pt (normal) oder h2 mit 12pt (wenn Sektion 1 = Inhaltsverzeichnis)
• Untertitel von Seite 1 als <p> darunter
• Kein Logo, keine Farben, keine Rahmen — nur einfacher Text

5. Schriftgrößen auf 11pt normalisiert

• normalize_font_sizes() erzwingt bei TOC-Dokumenten 11pt für Fließtext (p, li, span, div)
• Tabellen-Elemente (td, th) und Überschriften (h1-h6) bleiben unverändert
• h1=16pt, h2=12pt, h3/h4=11pt, p/li=11pt, footer=8pt

6. Footer als festes 4-Spalten-Template

• Immer 4 Spalten: Freigabe | Bearbeiter | Änderungsstand | Datum
• Seitenzahlen-Spalte wird immer entfernt (auch wenn Original 5 Spalten hat)
• Font-Size: 8pt, border: none
• Header-Zeile: Hintergrundfarbe je nach Typ (#E6B8B7 für VA, #B8CCE4 für Standard)

7. Dokumenttyp-Farben erzwungen

• Standard: Tabellen-Header #B8CCE4 (blau), VA: #E6B8B7 (rosa)
• Datenzellen kein Hintergrund
• Auch bei leicht abweichenden Original-Farben wird die Vorlagenfarbe erzwungen

8. Hierarchische Einrückung (hängende Einzüge)

h2: margin-left:0, padding-left:10pt, text-indent:-10pt
h3: margin-left:10pt, padding-left:12pt, text-indent:-12pt
h4: margin-left:22pt, padding-left:14pt, text-indent:-14pt
Content nach h2: margin-left:10pt
Content nach h3: margin-left:22pt
Content nach h4: margin-left:36pt

9. Content-Normalisierung (immer aktiv)

• Excessive Margins (>30pt, ≥5%) entfernt
• text-align: justify → entfernt
• Bold <p> mit Sektionsnummern → h2/h3/h4
• Serif-Fonts → Arial, Font-Family auf alle Elemente
• Gebrochene Absätze zusammengeführt
• Em-Dash-Listen → disc bullets
• Seitenübergreifende Tabellen zusammengeführt
• text-align: left auf alle Elemente

---

Andere Dokumente: 1:1 Konvertierung

Bei Dokumenten die NICHT VA oder Standard sind:

ALLES muss 1:1 wie im Original aussehen:

• Alle Hintergrundfarben exakt übernehmen (auch wenn nicht rosa/blau)
• Alle Rahmenlinien wie im Original
• Tabellenstrukturen exakt nachbilden
• Bilder und Grafiken einbinden
• Keine Vorlagen-Regeln anwenden!

Dokument hat grüne Header? → Grüne Header im HTML
Dokument hat graue Zellen? → Graue Zellen im HTML
Dokument hat keine Linien? → border: none im HTML

---

Document Type Detection

Standard Document

Detection criteria:

• Blue header backgrounds (#B8CCE4 or similar cool blue tones)
• Each section is a separate <table> with header row
• Content is in table cells, not free-flowing

Verfahrensanweisung (VA)

Detection criteria:

• Rosa/salmon header backgrounds (#F2DCDB, #E6B8B7 or similar warm tones)
• Free-flowing <h2> headings (not in tables)
• Only one procedure table (Section 4: Verfahrensablauf)

Other Documents

Detection criteria:

• No blue or rosa template colors
• No numbered section structure (1. 2. 3.)
• Any other document format

---

Template Rules: Standard (Blue)

Section Structure

Each section is a separate <table>:

<table border="1" style="border-collapse: collapse; width: 100%; font-family: Arial, sans-serif; font-size: 11pt;">
  <tr>
    <th style="border: 1px solid #000; padding: 4px; vertical-align: top; background-color: #B8CCE4; font-size: 12pt; font-weight: bold; text-align: left;">
      <p style="margin: 0; line-height: 1.5;">1. Ziel</p>
    </th>
  </tr>
  <tr>
    <td style="border: 1px solid #000; padding: 4px; vertical-align: top;">
      <p style="margin: 0; line-height: 1.5;">Dieser Standard regelt...</p>
    </td>
  </tr>
</table>

Steps Table (Durchführung) — MIT SPALTENBREITEN!

4-column table with colspan on header.

Standard-Spaltenbreiten: Nr=5%, Beschreibung=45%, Verantwortung=25%, Mittel=25% (Header colspan=50%)

<table border="1" style="border-collapse: collapse; width: 100%; font-family: Arial, sans-serif; font-size: 11pt; margin-top: 10px;">
  <tr>
    <th colspan="2" style="border: 1px solid #000; padding: 4px; vertical-align: top; background-color: #B8CCE4; font-size: 12pt; font-weight: bold; text-align: left; width: 50%;">
      <p style="margin: 0; line-height: 1.5;">3. Durchführung/Ablauf</p>
    </th>
    <th style="border: 1px solid #000; padding: 4px; vertical-align: top; background-color: #B8CCE4; font-size: 11pt; font-weight: bold; text-align: left; width: 25%;">
      <p style="margin: 0; line-height: 1.5;">Verantwortung</p>
    </th>
    <th style="border: 1px solid #000; padding: 4px; vertical-align: top; background-color: #B8CCE4; font-size: 11pt; font-weight: bold; text-align: left; width: 25%;">
      <p style="margin: 0; line-height: 1.5;">Mittel</p>
    </th>
  </tr>
  <tr>
    <td style="border: 1px solid #000; padding: 4px; vertical-align: top; background-color: #B8CCE4; text-align: center; width: 5%;">
      <p style="margin: 0; line-height: 1.5;">1</p>
    </td>
    <td style="border: 1px solid #000; padding: 4px; vertical-align: top; width: 45%;">
      <p style="margin: 0; line-height: 1.5;">Schritt 1</p>
    </td>
    <td style="border: 1px solid #000; padding: 4px; vertical-align: top;">
      <p style="margin: 0; line-height: 1.5;">MA</p>
    </td>
    <td style="border: 1px solid #000; padding: 4px; vertical-align: top;">
      <p style="margin: 0; line-height: 1.5;">Arbeitsmittel, Kommunikation</p>
    </td>
  </tr>
</table>

---

Template Rules: Verfahrensanweisung (Rosa)

Section Structure

Sections use free-flowing <h2> headings (KEINE Tabellen!):

<h2 id="sec-1" style="font-size: 12pt; font-weight: bold; margin: 10px 0 5px 0; font-family: Arial, sans-serif;">1. Zweck der Verfahrensanweisung</h2>
<p style="margin: 0 0 5px 0; line-height: 1.5; font-family: Arial, sans-serif; font-size: 11pt;">Mit dieser Verfahrensanweisung werden die Zuständigkeiten...</p>

Procedure Table (Verfahrensablauf) — MIT SPALTENBREITEN!

Only the procedure table (Section 4) uses table format.

VA-Spaltenbreiten: Nr=5%, Aufgabe=45%, Verantwortung=25%, Mittel=25% (Header colspan=50%)

<h2 id="sec-4" style="font-size: 12pt; font-weight: bold; margin: 10px 0 5px 0; font-family: Arial, sans-serif;">4. Beschreibung des Verfahrensablaufs</h2>
<table border="1" style="border-collapse: collapse; width: 100%; font-family: Arial, sans-serif; font-size: 11pt; margin-top: 10px;">
  <tr>
    <th colspan="2" style="border: 1px solid #000; padding: 4px; vertical-align: top; background-color: #E6B8B7; width: 50%;">
      <p style="margin: 0; line-height: 1.5;">Aufgabe</p>
    </th>
    <th style="border: 1px solid #000; padding: 4px; vertical-align: top; background-color: #E6B8B7; width: 25%;">
      <p style="margin: 0; line-height: 1.5;">Verantwortung</p>
    </th>
    <th style="border: 1px solid #000; padding: 4px; vertical-align: top; background-color: #E6B8B7; width: 25%;">
      <p style="margin: 0; line-height: 1.5;">Mittel</p>
    </th>
  </tr>
  <tr>
    <td style="border: 1px solid #000; padding: 4px; vertical-align: top; background-color: #E6B8B7; text-align: center; width: 5%;">
      <p style="margin: 0; line-height: 1.5;">1</p>
    </td>
    <td style="border: 1px solid #000; padding: 4px; vertical-align: top; width: 45%;">
      <p style="margin: 0; line-height: 1.5;">Task description</p>
    </td>
    <td style="border: 1px solid #000; padding: 4px; vertical-align: top;">
      <p style="margin: 0; line-height: 1.5;">MA</p>
    </td>
    <td style="border: 1px solid #000; padding: 4px; vertical-align: top;">
      <p style="margin: 0; line-height: 1.5;">Telefon</p>
    </td>
  </tr>
</table>

KRITISCH: Nr-Spalte hat GLEICHE Farbe wie Header (#E6B8B7), NICHT #F2DCDB!

Abbreviations Table (OHNE Rahmenlinien, ZENTRIERT!)

VA/Standard Abkürzungstabellen haben KEINE sichtbaren Rahmenlinien und sind ZENTRIERT:

KRITISCH: KEINE width: 100%! Zentrieren mit margin: 10px auto;!

<h3 id="sec-3.3" style="font-size: 11pt; font-weight: bold; margin: 10px 0 5px 20px; font-family: Arial, sans-serif;">3.3. Abkürzungen:</h3>
<table border="0" style="border-collapse: collapse; margin: 10px auto; font-family: Arial, sans-serif; font-size: 11pt;">
  <tr>
    <td style="border: none; padding: 4px; vertical-align: top;">
      <p style="margin: 0; line-height: 1.5;">MA</p>
    </td>
    <td style="border: none; padding: 4px 30px 4px 4px; vertical-align: top;">
      <p style="margin: 0; line-height: 1.5;">Mitarbeiter</p>
    </td>
    <td style="border: none; padding: 4px; vertical-align: top;">
      <p style="margin: 0; line-height: 1.5;">DP</p>
    </td>
    <td style="border: none; padding: 4px; vertical-align: top;">
      <p style="margin: 0; line-height: 1.5;">Dienstplan</p>
    </td>
  </tr>
</table>

---

Tabellen MIT vs. OHNE Rahmenlinien

Tabelle MIT sichtbaren Rahmenlinien:

<table border="1" style="border-collapse: collapse; ...">
  <td style="border: 1px solid #000; padding: 4px; vertical-align: top;">

Tabelle OHNE sichtbare Rahmenlinien:

<table border="0" style="border-collapse: collapse; ...">
  <td style="border: none; padding: 4px; vertical-align: top;">

---

Font-Größen und Normalisierung

Einheiten: Immer pt (nicht px!)

Alle Größenangaben in pt (Points), nicht px:

Element	Größe
h1 (Dokumenttitel)	14pt bold
h2 (Hauptsektionen)	12pt bold
h3 (Untersektionen)	11pt bold
Fließtext (p, li)	11pt
Tabellenzellen (td)	11pt
Footer-Tabelle	8pt

Post-Processing: normalize_font_sizes()

Automatische Normalisierung nach der Gemini-Konvertierung:

• Dokumente mit TOC → Fließtext wird auf 11pt normalisiert (Vorlagen-Standard)
• Dokumente ohne TOC → Erste verwendete Font-Größe wird als Baseline genommen

Unberührt bleiben:

• Tabellen (<td>, <th>) — behalten ihre eigene Größe
• Headings (<h1>-<h6>) — behalten ihre eigene Größe
• Bold-Tags (<strong>) — oft Überschriften, behalten ihre Größe

---

Color Reference

VA/Standard - NUR diese Farben!

Dokument-Typ	Header	Nummerierungsspalte	Datenzellen
Standard	#B8CCE4 (blau)	#B8CCE4 (blau)	transparent
VA	#E6B8B7 (rosa dunkel)	#F2DCDB (rosa hell)	transparent

Farbunterscheidung

Warm (Rosa/Lachs)	Cool (Blue)
#F2DCDB	#B8CCE4
#E6B8B7	#D9E2F3
#D99594	-

---

Seitenbild-Cropping (Header/Footer-Entfernung)

Gemini-basierte Crop-Erkennung (Phase 1)

Phase 1 sendet Pre-Content + 3 Content-Seiten an Gemini. Der RECOGNITION_PROMPT instruiert:

• "Vergleiche die Seiten. Alles was sich auf mind. 2 Seiten am oberen/unteren Rand wiederholt = Header/Footer"
• Seitenzahlen zählen auch dazu (Position gleich, nur Zahl ändert sich)
• header_bottom_percent und footer_top_percent sind physische Crop-Grenzen
• Beispiel: Footer-Trennlinie bei 88%, Text 89-91%, Balken 91-92% → footer_top_percent = 87.5

crop_page_images() — Physisches Cropping

Nach Phase 1 werden ALLE Seitenbilder physisch gecroppt:

crop_page_images(page_images, header_bottom_pct, footer_top_pct, margin_px=5)

• Header/Footer werden abgeschnitten bevor Gemini die Bilder in Phase 2b sieht
• Gemini kann NICHT durch Header/Footer verwirrt werden
• Prompts enthalten KEINE "IGNORIEREN!"-Sektionen mehr
• Stattdessen: "Die Seitenbilder zeigen NUR den Content-Bereich. Konvertiere ALLES."
• Original-Bilder bleiben für visuelle Verifikation erhalten

Vorteile des Croppings

1. Keine Header/Footer-Artefakte möglich (Gemini sieht sie nie)
2. Kürzere Prompts (keine "KOPFZEILE IGNORIEREN" Sektionen)
3. Keine Header/Footer-Referenzbilder → weniger Tokens → günstiger
4. Tabellenfortsetzung einfacher (Content reicht bis unterer Rand = Tabelle geht weiter)
5. Weniger Post-Processing nötig

---

Bild-Verarbeitung

Waifu2x Upscaling

Alle extrahierten Bilder werden automatisch mit waifu2x-converter-cpp hochskaliert:

• Skalierung: 2x (doppelte Auflösung)
• Noise Level: 2 (mittlere Rauschunterdrückung)
• Anzeige: Bilder werden im HTML mit Originalgrößen-Attributen angezeigt (width/height)

# Upscaling läuft automatisch nach Bildextraktion
image_orig_dimensions = upscale_images_in_dir(full_output, scale=2, noise=2)

Bild-Benennungsschema

Format: content_X_Y.png wobei:

• X = Seitennummer (1-basiert)
• Y = Fortlaufende Position im Dokument

Beispiele:

• content_1_1.png = Seite 1, Position 1 (oft Logo - Vorsicht!)
• content_2_2.png = Seite 2, Position 2
• content_6_5.png = Seite 6, Position 5

Duplikate (Bilder auf mehreren Seiten):

• Wenn ein Bild auf mehreren Seiten vorkommt → content_Y.png (ohne Seite)

Ganzseitige Bilder (Gescannte Dokumente)

Wenn eine Seite >90% von einem Bild bedeckt ist:

• Erkennung: coverage_w > 0.90 AND coverage_h > 0.90
• Verhalten: Seite wird NICHT an Gemini gesendet
• Ausgabe: Direktes <img> Tag im HTML

<!-- Seite 1: Ganzseitiges Bild (gescanntes Dokument) -->
<div style="margin: 20px 0; page-break-inside: avoid;">
  <img src="content_1_1.png" alt="Seite 1" style="max-width: 100%; height: auto;" width="596" height="842">
</div>

Vorteile:

• Keine API-Kosten für gescannte Seiten
• Schnellere Verarbeitung
• Originalqualität erhalten
• Kein OCR-Fehlerrisiko

Logo-Filterung

Automatische Erkennung und Ausfilterung von Logos:

Kriterium	Beschreibung
Header-Bereich	Top 12% der Seite (kleine Bilder)
Logo-artig	Top 20%, Höhe <60px, Ratio >2.0
Logo-Dimensionen	Höhe <50px, Ratio >2.5
Zu flach	Ratio >5.0
Hash-Duplikate	Gleiches Bild auf mehreren Seiten

Ausnahme: Große Bilder (>200x150) werden NIE als Logo gefiltert!

Vektorgrafik-Extraktion

PyMuPDF get_images() extrahiert nur Rasterbilder. Für Vektorgrafiken:

Erkennung:

• Seite hat >10 drawings
• Keine Rasterbilder auf der Seite extrahiert

Verarbeitung:

1. Gruppiere drawings nach Y-Position (±50px = gleiche Gruppe)
2. Rendere jede Gruppe als separates Bild mit zoom=1.0
3. Validiere mit Gemini ob es echte Grafik ist (nicht nur Text/Linien)

drawings = page.get_drawings()
if len(drawings) >= 10 and page_num not in pages_with_images:
    # Rendere Vektorgrafik-Gruppen

---

API Endpoints

POST /convert

Main conversion endpoint.

{
  "input": "tmp/upload_xxx/document.docx",
  "output_dir": "tmp/upload_xxx",
  "template_mode": "auto"
}

template_mode Options:

Mode	Beschreibung
"auto"	(Default) Automatische Erkennung. Wendet Standard/VA Vorlagen-Regeln an wenn erkannt.
"standard"	Erzwingt Standard-Vorlage (blaue Header #B8CCE4).
"va"	Erzwingt Verfahrensanweisung-Vorlage (rosa Header #E6B8B7).
"exact"	1:1 Konvertierung — KEINE Vorlagen-Anpassung! Alle Farben/Strukturen exakt wie im Original.

Wann welcher Modus?

• auto: Standard für normale Dokumente die einer Vorlage folgen
• standard/va: Erzwingen wenn das Dokument einer Vorlage folgen SOLL aber nicht erkannt wird
• exact: Für Import/Re-Check wenn das Dokument EXAKT wie das Original aussehen soll

Response:

{
  "success": true,
  "template_mode": "exact",
  "files": { "content": "content.html", "toc": "toc.html", ... }
}

POST /analyze-html

Quality analysis of generated HTML.

GET /health

Service health check.

---

Troubleshooting

Issue: Falsche Farben verwendet

Ursache: VA/Standard Template nicht erkannt oder falsche Farben generiert. Lösung: Prüfen ob Dokument rosa (VA) oder blau (Standard) Header hat. Nur Vorlagen-Farben verwenden!

Issue: Alle Datenzellen haben Hintergrundfarbe

Ursache: Farbregeln nicht befolgt. Lösung: NUR Header-Zeile und Nummerierungsspalte bekommen Hintergrundfarbe!

Issue: Logo/Bilder aus Header extrahiert

Ursache: Header-Behandlung falsch. Lösung: Aus Header NUR Dokumenttitel extrahieren, KEINE Bilder!

Issue: Abkürzungstabelle hat Rahmenlinien

Ursache: Tabellentyp nicht erkannt. Lösung: Abkürzungstabellen: border="0" und border: none;

Issue: Footer-Datenzellen haben Hintergrundfarbe

Ursache: Footer-Styling falsch. Lösung: Footer-Tabelle: NUR Header-Zeile mit Hintergrundfarbe!

Issue: Bilder werden nicht angezeigt (broken image icon)

Ursache: HTML referenziert content_N.png mit relativem Pfad. Lösung: Der doc-converter bettet Bilder automatisch als base64 Data-URI ein:

<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." alt="...">

Wenn Bilder trotzdem fehlen: Prüfen ob extract_pdf_images() die Bilder korrekt extrahiert.

Issue: h3-Überschriften fehlen im TOC

Ursache: TOC enthält nur h2-Level. Lösung: Alle h3 (3.1, 3.2, 3.3 etc.) müssen im TOC erscheinen mit margin-left: 20px;

Issue: Gescannte Seiten werden konvertiert

Ursache: Fullpage-Image-Erkennung nicht aktiv. Lösung: Prüfen ob fullpage_image_pages korrekt zurückgegeben wird. Bilder >90% coverage sollten als ganzseitig erkannt werden.

Issue: Bilder haben unterschiedliche Qualität

Ursache: Verschiedene Extraktionsmethoden. Lösung: Alle Bilder werden jetzt einheitlich mit zoom=1.0 gerendert und dann mit waifu2x 2x hochskaliert.

Issue: Kleine Icons/Elemente auf gescannten Seiten

Ursache: Zusätzliche kleine Bilder auf einer fullpage-Seite werden auch angezeigt. Lösung: Das ist erwartetes Verhalten. Das große ganzseitige Bild und eventuelle kleine Elemente werden beide angezeigt.

---

Jodit Editor Compatibility

REQUIRED for Jodit:

• All styles as inline style="..." attributes
• No <style> tags
• No <colgroup> or <col> tags
• No <thead> or <tbody> tags
• Text in table cells wrapped in <p> tags
• Every <td> and <th> needs vertical-align: top;

FORBIDDEN:

• CSS classes (no class="...")
• External stylesheets
• Empty separator rows
• Columns with width: 0%