Sebastian Unterschütz
157 lines
4.3 KiB
Markdown
157 lines
4.3 KiB
Markdown
# Markdown → IHK Chemnitz PDF Converter
|
||
|
||
Converts Markdown files into compliant project documentation for **IHK Chemnitz**
|
||
IT vocational exams (Verordnung 2020).
|
||
|
||
---
|
||
|
||
## IHK Formatting Requirements
|
||
|
||
All rules below are enforced automatically. Deviating from them can lead to
|
||
grade deductions (*"kann zu Punktabzug bei der Bewertung führen"*).
|
||
|
||
| Rule | Value | Note |
|
||
|---|---|---|
|
||
| Font | Helvetica / Arial, black | PDF-safe equivalent |
|
||
| Body size | 12 pt | |
|
||
| Heading size | 14 pt, bold | |
|
||
| Caption / footnote size | 10 pt | |
|
||
| Line spacing | 1½ lines (6.35 mm) | |
|
||
| Alignment | Justified (Blocksatz) | |
|
||
| Left margin | 3.0 cm | |
|
||
| **Right margin** | **4.0 cm** | **Korrekturrand** — examiners write feedback here |
|
||
| Top margin | 2.0 cm | |
|
||
| Bottom margin | 2.5 cm | |
|
||
| Paper | DIN A4, single-sided | |
|
||
| Front-matter numbering | Roman, starting at **II** | Title page is unnumbered |
|
||
| Body numbering | Arabic, starting at **1** | Centered at the bottom |
|
||
|
||
## Document Structure
|
||
|
||
The tool produces all required sections in the mandatory IHK order:
|
||
|
||
```
|
||
1. Title page · no page number
|
||
2. Table of contents · Roman II
|
||
3. List of abbrev. · Roman (optional, from YAML)
|
||
4. Foreword / body · Roman → Arabic via Markdown headings
|
||
5. Bibliography · Arabic (auto-sorted A–Z)
|
||
6. List of tables · Arabic (auto-generated)
|
||
7. List of figures · Arabic (auto-generated)
|
||
8. Appendix · Arabic (via @Anhang: directives)
|
||
9. Glossary · Arabic (optional, from YAML)
|
||
10. Declaration · no page number (pre-written legal text)
|
||
```
|
||
|
||
## Installation
|
||
|
||
Requires [Go](https://golang.org/) 1.22 or newer.
|
||
|
||
```bash
|
||
git clone <repository-url>
|
||
cd MarkdownToIHKChemnits
|
||
go mod tidy
|
||
```
|
||
|
||
## Usage
|
||
|
||
```bash
|
||
go run . -i report.md -o projektarbeit.pdf
|
||
```
|
||
|
||
| Flag | Default | Description |
|
||
|---|---|---|
|
||
| `-i` | `report.md` | Input Markdown file |
|
||
| `-o` | `projektarbeit.pdf` | Output PDF file |
|
||
|
||
## YAML Front Matter
|
||
|
||
Every Markdown file starts with a YAML block that drives the title page,
|
||
abbreviation list, and glossary:
|
||
|
||
```yaml
|
||
---
|
||
student:
|
||
name: "Max Mustermann"
|
||
profession: "Fachinformatiker Fachrichtung Anwendungsentwicklung"
|
||
company: "Musterfirma GmbH"
|
||
supervisor: "Sabine Supervisor"
|
||
project:
|
||
title: "Title of the project"
|
||
period: "Summer 2026"
|
||
|
||
# Optional — generates Abkürzungsverzeichnis
|
||
abbreviations:
|
||
- abbr: "API"
|
||
meaning: "Application Programming Interface"
|
||
- abbr: "DIN"
|
||
meaning: "Deutsches Institut für Normung"
|
||
|
||
# Optional — generates Glossar
|
||
glossary:
|
||
- term: "Goldmark"
|
||
definition: "A CommonMark-compliant Markdown parser written in Go."
|
||
---
|
||
```
|
||
|
||
## Markdown Directives
|
||
|
||
Special directives inside paragraphs control bibliography, appendix, and diagrams:
|
||
|
||
```markdown
|
||
# Vorwort
|
||
This section uses Roman page numbers.
|
||
|
||
# 1. Problem Statement
|
||
Any numbered or unknown heading switches to Arabic numbering.
|
||
|
||
# Inline formatting
|
||
**Bold** and *italic* text are preserved in the PDF output.
|
||
|
||
# Bibliography entries
|
||
@Quelle: Author, Title, Publisher, Year
|
||
> Quelle: Alternative blockquote syntax also works
|
||
|
||
# Appendix images
|
||
@Anhang: Description | /path/to/image.png
|
||
|
||
# UML diagram as appendix (rendered via Kroki)
|
||
@AnhangUML: Sequence Diagram Title
|
||
` ``puml
|
||
@startuml
|
||
A -> B: request
|
||
@enduml
|
||
` ``
|
||
|
||
# Inline diagrams (rendered via Kroki, embedded in body)
|
||
` ``mermaid
|
||
graph TD
|
||
A --> B
|
||
` ``
|
||
```
|
||
|
||
Diagrams are rendered via [Kroki.io](https://kroki.io) and cached locally
|
||
using the SHA-256 hash of the diagram source as the cache key.
|
||
|
||
## Project Structure
|
||
|
||
```
|
||
MarkdownToIHKChemnits/
|
||
│
|
||
├── main.go Entry point; two-pass rendering pipeline
|
||
├── config.go Config struct (student, project, abbreviations, glossary)
|
||
│
|
||
├── markdown_parser.go Goldmark AST walker; inline span extraction; directives
|
||
├── diagram.go Kroki.io integration (Mermaid, PlantUML, …)
|
||
│
|
||
├── pdf_renderer.go IHKRenderer struct; DIN 5008 constants; core helpers
|
||
├── pdf_numbering.go NumberingType enum; toRoman()
|
||
├── pdf_toc.go Table of contents; list of tables; list of figures
|
||
├── pdf_pages.go Title, declaration, bibliography, appendix, abbrev., glossary
|
||
└── pdf_content.go Headings, paragraphs, tables, images, list items
|
||
```
|
||
|
||
## License
|
||
|
||
MIT
|