# MarkdownToIHKChemnitz

A Go CLI tool that converts a single Markdown file into a print-ready PDF compliant with the **IHK Chemnitz project documentation guidelines** (Verordnung 2020) and **DIN 5008** formatting rules.

## Features

- DIN 5008 page layout — correct margins, font, line spacing, Blocksatz
- Two-pass rendering for a page-accurate table of contents
- Roman/Arabic page numbering with automatic section detection
- Multi-line table cells with uniform row height per row
- Named tables (*Tabellenverzeichnis*) and captioned figures (*Abbildungsverzeichnis*)
- Numbered code blocks with line-number gutter and long-line wrapping
- Diagram rendering via [Kroki](https://kroki.io) — Mermaid, PlantUML, and more
- Inline landscape diagram pages (`@DiagrammQuer:`)
- Appendices in portrait **and landscape** — images, tables, and diagrams
- Abbreviation list and glossary from YAML front matter
- Bibliography sorted alphabetically from inline `@Quelle:` directives
- Declaration of authenticity page (pre-written legal text)

---

## Prerequisites

- Go 1.22 or later
- Internet access **or** a local Kroki instance for diagram rendering (see below)

---

## Build & Run

```bash
go build -o ihk-pdf .
./ihk-pdf -i report.md -o projektarbeit.pdf
```

Or without building:

```bash
go run . -i report.md -o projektarbeit.pdf
```

---

## CLI Flags

| Flag | Default | Description |
|------|---------|-------------|
| `-i` | `report.md` | Input Markdown file |
| `-o` | `projektarbeit.pdf` | Output PDF file |
| `-kroki` | `https://kroki.io` | Kroki base URL for diagram rendering |

---

## Diagram Rendering with Kroki

Mermaid and PlantUML fenced code blocks are rendered server-side via [Kroki](https://kroki.io). The resulting PNG is cached locally using a SHA-256 hash of the diagram source, so unchanged diagrams are not re-fetched.

By default the public instance at `https://kroki.io` is used. If your network blocks it, run a local instance with Docker Compose:

**`docker-compose.yml`**

```yaml
services:
  kroki:
    image: yuzutech/kroki
    environment:
      - KROKI_MERMAID_HOST=mermaid
    ports:
      - "8000:8000"
    depends_on:
      - mermaid
  mermaid:
    image: yuzutech/kroki-mermaid
    expose:
      - "8002"
```

```bash
docker compose up -d
go run . -i report.md -kroki http://localhost:8000 -o projektarbeit.pdf
```

> **Note:** The base `yuzutech/kroki` image does not include a Mermaid renderer. The companion `yuzutech/kroki-mermaid` container is required, wired via `KROKI_MERMAID_HOST=mermaid`.

---

## YAML Front Matter

Every input file begins with a YAML block delimited by `---`. All fields are optional except where noted.

```yaml
---
student:
  name: "Max Mustermann"                                    # required
  profession: "Fachinformatiker Fachrichtung Anwendungsentwicklung"
  company: "Musterfirma GmbH"
  supervisor: "Sabine Supervisor"

project:
  title: "Titel der Projektarbeit"                         # required
  subtitle: "Optionaler Untertitel"                        # optional
  period: "Sommer 2026"

abbreviations:                                             # optional → Abkürzungsverzeichnis
  - abbr: "API"
    meaning: "Application Programming Interface"
  - abbr: "IHK"
    meaning: "Industrie- und Handelskammer"

glossary:                                                  # optional → Glossar (after appendices)
  - term: "Goldmark"
    definition: "Ein CommonMark-konformer Markdown-Parser für Go."
---
```

---

## Document Structure

The generated PDF follows the mandatory IHK Chemnitz order:

| # | Section | Page Numbering |
|---|---------|----------------|
| 1 | Title page | none |
| 2 | Table of contents | Roman (II, III, …) |
| 3 | Abbreviation list | Roman (from YAML, optional) |
| 4 | Foreword / front-matter sections | Roman |
| 5 | Main body chapters | Arabic (1, 2, …) |
| 6 | Bibliography | Arabic |
| 7 | List of tables | Arabic |
| 8 | List of figures | Arabic |
| 9 | Appendices | Arabic |
| 10 | Glossary | Arabic (from YAML, optional) |
| 11 | Declaration of authenticity | none |

### Front-matter detection

Level-1 headings named `Vorwort`, `Einleitung`, or `Abkürzungsverzeichnis` stay in the Roman-numbered front matter. Every other level-1 heading triggers the switch to Arabic numbering.

---

## DIN 5008 / IHK Formatting Rules

| Property | Value |
|----------|-------|
| Paper | A4 |
| Left margin | 30 mm |
| Right margin (Korrekturrand) | 40 mm |
| Top margin | 20 mm |
| Bottom margin | 25 mm |
| Body font | Helvetica (Arial) 12 pt, black |
| Body line spacing | 1.5× → 6.35 mm |
| Heading font | Helvetica Bold 14 pt |
| Caption / footnote | Helvetica 10 pt |
| List line spacing | 1.2× → 5.0 mm |
| Alignment | Justified (Blocksatz) |
| Page number position | Centered at bottom |

---

## Directives

Directives are plain paragraphs starting with `@`. They are consumed by the parser and never appear in the PDF as raw text. Multiple directives may appear in a single paragraph, one per line.

---

### `@Quelle:` — Bibliography entry

```
@Quelle: Autor, Titel, Verlag, Jahr
```

Registers a bibliography entry. All entries are collected and rendered alphabetically at the end of the document in the *Literaturverzeichnis*. May appear anywhere in the document, any number of times.

---

### `@Tabelle:` — Named table

Place immediately before a Markdown table to assign it a name and record it in the *Tabellenverzeichnis*:

```
@Tabelle: Übersicht der Programmiersprachen

| Sprache | Paradigma | Typsystem |
|---------|-----------|-----------|
| Go      | Imperativ | Statisch  |
| Python  | Multi     | Dynamisch |
```

---

### `@TabelleAnhang:` — Table as portrait appendix

Sends the following table to the appendix on a **portrait** A4 page as a numbered *Anlage*:

```
@TabelleAnhang: Vollständige Fehlerliste

| Code | Beschreibung       | Schwere  |
|------|--------------------|----------|
| E001 | Datei nicht gefunden | Kritisch |
```

---

### `@TabelleAnhangQuer:` — Table as landscape appendix

Same as `@TabelleAnhang:` but placed on a **landscape** A4 page (297 × 210 mm, 15 mm symmetric margins). Use for wide tables that do not fit in portrait:

```
@TabelleAnhangQuer: Breite Vergleichsmatrix

| Kriterium | Option A | Option B | Option C | Option D |
|-----------|----------|----------|----------|----------|
| Leistung  | Gut      | Sehr gut | Befriedigend | Gut  |
```

---

### `@Anhang:` — Image as portrait appendix

```
@Anhang: Netzwerkdiagramm | diagrams/network.png
```

Adds an image file as a numbered *Anlage* on a **portrait** appendix page. The format is `Title | relative/path/to/image`.

---

### `@AnhangBildQuer:` — Image as landscape appendix

```
@AnhangBildQuer: Großes Architekturdiagramm | diagrams/arch.png
```

Same as `@Anhang:` but placed on a **landscape** A4 page. Useful for wide images.

---

### `@AnhangUML:` — Diagram as portrait appendix

Renders the immediately following Mermaid or PlantUML code block via Kroki and places the result as a numbered *Anlage* on a **portrait** appendix page:

```
@AnhangUML: Datenbankschema

` ``plantuml
@startuml
entity User {
  + id : int
  + name : string
}
@enduml
` ``
```

---

### `@AnhangUMLQuer:` — Diagram as landscape appendix

Same as `@AnhangUML:` but placed on a **landscape** A4 page with 15 mm symmetric margins. Use for complex diagrams that need more horizontal space:

```
@AnhangUMLQuer: Vollständige Modulübersicht

` ``mermaid
graph TD
    A --> B --> C
` ``
```

---

### `@DiagrammQuer:` — Inline landscape diagram page

Renders the following diagram on a **dedicated landscape page inline** in the document (not in the appendix). A figure caption is added and the figure is recorded in the *Abbildungsverzeichnis*. A fresh portrait page opens automatically afterwards:

```
@DiagrammQuer: Systemarchitektur – Zwei-Pass-Rendering

` ``mermaid
graph LR
    MD[report.md] --> Parser --> AST --> Renderer --> PDF
` ``
```

---

## Directive Summary Table

| Directive | Format | Placement | Orientation |
|-----------|--------|-----------|-------------|
| `@Quelle:` | `@Quelle: Text` | Inline anywhere | — |
| `@Tabelle:` | `@Tabelle: Name` | Before a table | — |
| `@TabelleAnhang:` | `@TabelleAnhang: Name` | Before a table | Portrait appendix |
| `@TabelleAnhangQuer:` | `@TabelleAnhangQuer: Name` | Before a table | **Landscape** appendix |
| `@Anhang:` | `@Anhang: Title \| path` | Standalone | Portrait appendix |
| `@AnhangBildQuer:` | `@AnhangBildQuer: Title \| path` | Standalone | **Landscape** appendix |
| `@AnhangUML:` | `@AnhangUML: Title` | Before diagram block | Portrait appendix |
| `@AnhangUMLQuer:` | `@AnhangUMLQuer: Title` | Before diagram block | **Landscape** appendix |
| `@DiagrammQuer:` | `@DiagrammQuer: Caption` | Before diagram block | **Landscape** inline page |

---

## File Structure

```
.
├── main.go              # Entry point, CLI flags, two-pass pipeline
├── config.go            # Config struct matching the YAML front matter
├── markdown_parser.go   # Goldmark AST walker, directive handling
├── pdf_renderer.go      # IHKRenderer struct, DIN 5008 constants, appendix registry
├── pdf_content.go       # Paragraphs, lists, tables, images, code blocks
├── pdf_toc.go           # TOC, list of tables, list of figures
├── pdf_pages.go         # Title page, declaration, bibliography, appendices, glossary
├── pdf_numbering.go     # Roman/Arabic page numbering helpers
├── diagram.go           # Kroki HTTP client, SHA-256 image cache
├── docker-compose.yml   # Local Kroki + kroki-mermaid containers
└── report.md            # Sample document demonstrating all features
```

---

## Two-Pass Rendering

The tool renders the document twice:

1. **Pass 1** — full render into a scratch PDF to collect the page number of every heading, table, and figure.
2. **Pass 2** — final render using the TOC index from pass 1, producing the output PDF.

Only `tocItems` are transferred between passes. `tableItems` and `figureItems` are rebuilt during pass 2 to avoid duplicates in the respective lists.

---

## Landscape Pages — Technical Notes

- Landscape appendices and `@DiagrammQuer:` use `fpdf.AddPageFormat("L", {Wd:297, Ht:210})` with 15 mm symmetric margins. No 40 mm Korrekturrand — examiners do not annotate diagram or data pages.
- After any landscape page, `AddPage()` reverts to the default portrait orientation (A4 "P") set at construction time — no explicit orientation restore is needed for subsequent content.
- Portrait margins (30/20/40 mm) are restored immediately after the landscape page is closed so all following content is formatted correctly.

---

## License

MIT