# Markdown-Format: Vollständiger Leitfaden für die Arbeit mit KI und Automatisierung
> Umfassender praktischer Leitfaden zur Markdown-Syntax für die KI-Entwicklung: CommonMark, Überschriftenhierarchie, GFM-Tabellen, Escaping, System-Prompts und CLAUDE.md-Dateien.
## 1. Was ist Markdown: Philosophie, CommonMark und warum es die Muttersprache der KI ist
**Markdown** ist eine leichtgewichtige Auszeichnungssprache für Text, die 2004 von John Gruber mit einem einfachen Ziel entwickelt wurde: strukturierten Text zu schreiben, der im Rohzustand maximal lesbar bleibt und sich problemlos in valides HTML konvertieren lässt. Der moderne Referenzstandard des Formats ist in der **CommonMark**-Spezifikation definiert und durch den Standard **GitHub Flavored Markdown (GFM)** erweitert.
In der Interaktion mit künstlicher Intelligenz (ChatGPT, Claude Code, Gemini, lokale Modelle via Ollama) ist Markdown die primäre Kommunikationssprache.
```mermaid
flowchart LR
A["Сирий текст Markdown
(Мінімальна вага, чистий UTF-8)"] --> B["LLM / AI-агент
(Точне розуміння семантики)"]
B --> C{"Парсинг та рендеринг"}
C --> D["HTML / Вебсайти
(Заголовки, списки, таблиці)"]
C --> E["DOCX / PDF звіти
(Конвертація через Pandoc)"]
C --> F["Системний контекст
(CLAUDE.md, .cursorrules)"]
```
### Warum große Sprachmodelle „in Markdown denken“
1. **Ideale Token-Ökonomie:** Im Gegensatz zu XML oder HTML, bei denen jedes Tag einen Öffnungs- und einen Schließungs-TAG erfordert (`Text
`), verwendet Markdown nur minimale Steuerzeichen oder einfache Zeilenumbrüche.
2. **Semantische Eindeutigkeit:** Die Symbole `#`, `-`, `>` sowie Inline-Code-Marker belasten das Kontextfenster nicht unnötig und geben dem Modell eine klare Karte der Gedanken-Hierarchie.
3. **Natürlichkeit für Streaming-Ausgabe:** Die Wort-für-Wort-Generierung ohne komplexe, ungeschlossene Tags ermöglicht das sofortige Rendern der Formatierung im Chat-Interface („on the fly“).
4. **Versionskontrolle in Git:** `.md`-Dateien sind reine Textdateien, weshalb Änderungen an Wissensdatenbanken oder Dokumentationen einfach über `git diff` nachvollziehbar sind.
> [!NOTE]
> Die Formatierung in Markdown unterscheidet zwei Ebenen: **Blockelemente** (Überschriften, Listen, Zitate, Tabellen, Codeblöcke) und **Inline-Elemente** (Fett, Kursiv, Links, Inline-Code). Blockelemente müssen zwingend durch eine Leerzeile voneinander getrennt werden.
---
## 2. Überschriftenhierarchie und Navigationsstruktur von Dokumenten
Überschriften bilden das Skelett eines Dokuments und generieren das Inhaltsverzeichnis (Table of Contents). In Markdown werden die Überschriftenebenen durch das Raute-Zeichen (`#`) am Zeilenanfang gekennzeichnet – von eins bis sechs.
| Überschriftenebene | Markdown-Syntax | HTML-Äquivalent | Typische Verwendung |
| :--- | :--- | :--- | :--- |
| **Ebene 1** | `# Überschrift` | `` | Titel des gesamten Artikels oder Dokuments (nur einmal pro Seite) |
| **Ebene 2** | `## Überschrift` | `` | Hauptabschnitte und zentrale Module des Themas |
| **Ebene 3** | `### Überschrift` | `` | Unterabschnitte, Schritte in Anleitungen, einzelne Tools |
| **Ebene 4** | `#### Überschrift` | `` | Detaillierung von Unterpunkten, Parameter, Hinweise |
| **Ebene 5** | `##### Überschrift` | `` | Kleine technische Fußnoten |
| **Ebene 6** | `###### Überschrift` | `` | Mikroüberschriften in Spezifikationen |
### Kritische Regel: Leerzeichen nach der Raute
Gemäß dem CommonMark-Standard muss zwischen dem Raute-Zeichen und dem Überschriftentext **zwingend** ein einzelnes Leerzeichen stehen. Fehlt dieses Leerzeichen, interpretieren die meisten modernen Parser den Eintrag als gewöhnlichen Hashtag oder reinen Text.
> [!WARNING]
> Verwenden Sie niemals das Symbol `#` für eine H1-Überschrift innerhalb des Artikelkörpers, wenn der Titel bereits in den Metadaten (Frontmatter) definiert ist. Eine Seite sollte genau ein semantisches ``-Tag enthalten.
---
## 3. Textformatierung: Fett, Kursiv, Durchgestrichen und Sonderzeichen
Inline-Hervorhebungen helfen dabei, die Aufmerksamkeit auf Schlüsselbegriffe und Konzepte zu lenken.
| Stil der Hervorhebung | Markdown-Syntax | Anzeigeergebnis |
| :--- | :--- | :--- |
| **Fett (Bold)** | `**wichtiger Begriff**` oder `__Begriff__` | **wichtiger Begriff** |
| **Kursiv (Italic)** | `*Akzent*` oder `_Akzent_` | *Akzent* |
| **Fett-Kursiv** | `***kritische Aktion***` | ***kritische Aktion*** |
| **Durchgestrichen (Strikethrough)** | `~~veraltete Version~~` | ~~veraltete Version~~ |
| **Inline-Code** | `` `apiKey` `` | `apiKey` |
### Praktische typografische Nuancen
- **Hervorhebung innerhalb eines Wortes:** Wenn Sie einen Teil eines Wortes hervorheben möchten, verwenden Sie immer Sternchen (`A*cat*meow`), da einige Prozessoren Unterstriche innerhalb von Wörtern ignorieren und sie als Teil einer Variablen-ID interpretieren (`user_profile_id`).
- **Zeilenumbruch ohne neuen Absatz:** Um einen Zeilenumbruch (`
`) innerhalb desselben Absatzes hinzuzufügen, setzen Sie zwei Leerzeichen ans Ende der Zeile oder nutzen Sie das Tag `
`.
- **Kommentare:** Für Notizen, die nicht auf der finalen Seite gerendert werden sollen, verwenden Sie die Syntax von HTML-Kommentaren: ``.
---
## 4. Listen und verschachtelte Strukturen: nummeriert, Aufzählung und Checkboxen
Listen strukturieren schrittweise Algorithmen und Parametersätze.
### Aufzählungs- und nummerierte Listen
:::tabs
@tab Aufzählungsliste
```markdown
- Перший пункт плану
- Другий пункт плану
- Вкладений підпункт (відступ 2 або 4 пробіли)
- Ще один вкладений підпункт
- Третій пункт плану
```
@tab Nummerierte Liste
```markdown
1. Завантажте репозиторій
2. Встановіть залежності
3. Запустіть сервер розробки
```
@tab Interaktive Checkboxen (Task Lists)
```markdown
- [x] Створити файл конфігурації
- [x] Налаштувати підключення до бази даних
- [ ] Запустити інтеграційні тести
```
:::
### Zusätzliche Blöcke innerhalb von Listen
Um einen Absatz, ein Zitat oder einen Codeblock innerhalb eines Listenelements einzufügen, ohne die Gesamt-Numerierung zu unterbrechen, rücken Sie jede untergeordnete Zeile um 4 Leerzeichen ein:
```markdown
1. Запустіть процес збірки проєкту:
```bash
npm run build
```
> [!NOTE]
> Переконайтеся, що змінні оточення у файлі `.env` налаштовані правильно перед запуском.
2. Перевірте вихідний каталог `dist/`.
```
---
## 5. Links, Bilder und korrekte URL-Codierung
Die Syntax für Links und Mediendateien basiert auf der Kombination aus eckigen und runden Klammern.
### Grundlegende Link-Konstrukte
- **Einfacher Inline-Link:** `[Anthropic Dokumentation](https://docs.anthropic.com)`
- **Link mit Tooltip (title):** `[Claude Code](https://claude.ai "Offizielle Website")`
- **Autolinks:** `` oder ``
- **Bild:** `[Beschreibung des Bildes für Barrierefreiheit](/images/diagram.webp "Tooltip")`
- **Klickbares Bild-Link:** `[](https://example.com)`
### Korrekte Codierung von Sonderzeichen in URLs
Wenn eine URL Leerzeichen, runde Klammern oder kyrillische Zeichen enthält, bricht die direkte Einfügung die Markdown-Link-Syntax. Diese Zeichen müssen zwingend durch Prozent-Codes ersetzt werden (URL Percent-Encoding):
```markdown
[Стаття з Вікіпедії](https://uk.wikipedia.org/wiki/Комп%27ютер_%28значення%29)
[Стаття з Вікіпедії](https://uk.wikipedia.org/wiki/Комп'ютер_(значення))
```
---
## 6. Inline-Code, Codeblöcke und Syntax-Highlighting
Code und Konfigurationen erfordern eine Monospace-Schriftart und Schutz vor der Interpretation interner Zeichen.
### Inline-Code vs. Fenced Code Blocks
- **Inline-Code:** Einzelne Backticks (Gravis-Zeichen): `git status`.
- **Escaping eines Backticks innerhalb von Inline-Code:** Umschließen mit doppelten Backticks: `` `npm test` ``.
- **Fenced Code Blocks:** Drei Backticks mit zwingender Angabe des Sprach-Identifiers.
```typescript
interface UserProfile {
id: string;
username: string;
isActive: boolean;
}
export function formatUser(user: UserProfile): string {
return `@${user.username} (ID: ${user.id})`;
}
```
> [!IMPORTANT]
> **Strenge Isolierungsregel für Prompts:** Alle System-Prompts oder Assistenten-Regeln (`.cursorrules`, `CLAUDE.md`), die eigene Überschriften-Symbole (`#`, `##`) enthalten, **müssen** zwingend in einen separaten Codeblock mit Sprachangabe (z. B. markdown oder text) eingebettet werden. Bleiben sie ohne Codeblock im Fließtext, landen die internen Prompt-Überschriften im Inhaltsverzeichnis (TOC) des Artikels und zerstören die Seiten-Navigation.
---
## 7. Zitate, Callouts und horizontale Trennlinien
Zitate werden durch das Symbol `>` am Zeilenanfang erzeugt und dienen zur Hervorhebung von Gedanken, wichtigen Warnungen oder zum Zitieren von Text.
### Standard-Zitate und mehrstufige Verschachtelung
```markdown
> Це цитата першого рівня.
>
> > Це вкладена цитата другого рівня всередині попередньої.
```
### Moderne GitHub Alerts (Callout-Blöcke)
Moderne Dokumentationsplattformen unterstützen standardisierte hervorgehobene Blöcke mit farbigen Icons:
```markdown
> [!NOTE]
> Корисна довідкова інформація або контекст для розуміння.
> [!TIP]
> Порада щодо оптимізації, підвищення ефективності чи найкраща практика.
> [!IMPORTANT]
> Критично важлива інформація, обов'язкова до виконання.
> [!WARNING]
> Застереження про потенційні помилки, збої або втрату даних.
```
### Horizontale Trennlinien
Drei oder mehr Bindestriche (`---`), Sternchen (`***`) oder Unterstriche (`___`) in einer eigenen Zeile erzeugen eine horizontale Linie:
```markdown
Текст попереднього розділу.
---
Текст наступного розділу після розділювача.
```
---
## 8. Escaping von Sonderzeichen und eingebettetes HTML
Wenn ein Markdown-Syntax-Zeichen als normales Druckzeichen ausgegeben werden soll, wird ihm ein Backslash (`\`) vorangestellt.
### Liste der zu escapenden Zeichen
| Zeichen | Name des Zeichens | Beispiel für Escaping | Render-Ergebnis |
| :--- | :--- | :--- | :--- |
| `\` | Backslash | `\\` | \ |
| `` ` `` | Backtick | `` \` `` | ` |
| `*` | Asterisk (Stern) | `\*nicht kursiv\*` | \*nicht kursiv\* |
| `_` | Underscore (Unterstrich) | `\_nicht fett\_` | \_nicht fett\_ |
| `#` | Hash (Raute) | `\# Keine Überschrift` | \# Keine Überschrift |
| `[` `]` | Eckige Klammern | `\[Kein Link\]` | \[Kein Link\] |
| `!` | Ausrufezeichen | `\!Kein Bild` | \!Kein Bild |
### Sichere Nutzung von HTML
Reicht Standard-Markdown nicht aus, können HTML-Tags verwendet werden, wobei folgende Einschränkungen zu beachten sind:
- Das Tag `
` für erzwungene Zeilenumbrüche in Tabellen.
- Das Tag `` für unterstrichenen Text.
- Block-Tags (``, `
`) müssen durch Leerzeilen vom Markdown-Code getrennt werden; innerhalb dieser Tags funktioniert die Markdown-Auszeichnung nicht.
---
## 9. GitHub Flavored Markdown (GFM)-Tabellen und Mermaid-Diagramme
Tabellen ermöglichen den Vergleich von Eigenschaften, Parametern und Konfigurationen.
### GFM-Tabellen-Syntax mit Ausrichtung
```markdown
| Параметр | Опис функціональності | Значення за замовчуванням | Статус |
| :--- | :--- | :---: | ---: |
| `apiKey` | Секретний ключ авторизації | `null` | Обов'язковий |
| `timeout` | Максимальний час очікування | `5000` | Опціональний |
| `retries` | Кількість повторних спроб | `3` | Рекомендовано |
```
- `:---` — Spaltenausrichtung linksbündig.
- `:---:` — Spaltenausrichtung zentriert.
- `---:` — Spaltenausrichtung rechtsbündig (ideal für Preise und Zahlen).
### Architekturvisualisierung über Mermaid
Anstelle schwerer Raster-Screenshots nutzen moderne Entwickler eingebettete Textdiagramme mit Mermaid:
```mermaid
sequenceDiagram
autonumber
actor User as Розробник
participant AI as Claude Code / GPT-4o
participant FS as Файлова система
User->>AI: Запит на генерацію документації
AI->>AI: Побудова структури в пам'яті (CommonMark)
AI->>FS: Запис файлу README.md
FS-->>User: Готовий структурований артефакт
```
---
## 10. Markdown in AI-Agenten: CLAUDE.md, System Prompts und Validierungs-Checkliste
Im Zeitalter autonomer AI-Agenten (Claude Code, Cursor, Windsurf, Devin) ist Markdown zur Hauptsprache für die Übermittlung des Engineering-Kontexts geworden.
### Projekt-Instruktionsdateien (CLAUDE.md / .cursorrules)
Agenten lesen die Root-Datei `CLAUDE.md` vor jeder Anfrage. Ist diese qualitativ hochwertig formatiert, hält sich das Modell fehlerfrei an die Projektarchitektur:
```markdown
Інженерні стандарти проєкту
===========================
1. Команди збірки та тестування:
- Збірка: npm run build
- Запуск юніт-тестів: npm test
- Лінтер: npm run lint
2. Архітектурні правила:
- Використовувати тільки Server Components за замовчуванням.
- Усі типи зберігати в каталозі src/types/.
- Жодних any у коді TypeScript.
```
### Master-Prompt für die Generierung einwandfreien Markdowns
```markdown
Дій як провідний технічний редактор та експерт із документації. Створи технічну документацію за специфікацією CommonMark / GFM.
Тема: [Вкажіть тему, наприклад: Архітектура мікросервісу автентифікації]
Вимоги до розмітки:
1. Заголовки строго від ## 1. до ## N. (Жодного # у тілі документа).
2. Завжди став одинарний пробіл після знаків решітки (наприклад, "## 1. Вступ", а не "##1. Вступ").
3. Усі фрагменти коду оформлюй у потрійні бектіки із зазначенням мови (typescript, bash, json, mermaid).
4. Порівняльні матриці подавай у валідних GFM-таблицях із вирівнюванням колонок.
5. Для важливих застережень використовуй callout-блоки (> [!NOTE], > [!WARNING]).
6. Посилання з пробілами або дужками мають містити percent-encoded URL (%20, %28, %29).
Виведи чистий, готовий до публікації Markdown-документ.
```
### Checkliste zur Prüfung der Markdown-Qualität
- [ ] Im Artikelkörper befindet sich kein `#`-Tag (H1 wird ausschließlich aus dem Seitentitel generiert).
- [ ] Alle Abschnitte der obersten Ebene sind sequenziell nummeriert (`## 1.`, `## 2.`).
- [ ] Nach den Raute-Zeichen `#` steht zwingend ein Leerzeichen.
- [ ] Alle Prompts, Konfigurationen und Codebeispiele sind in entsprechende `` ``` ``-Blöcke eingebettet.
- [ ] Sonderzeichen in Links sind korrekt codiert (Percent-Encoding).
- [ ] Tabellen folgen dem GFM-Standard ohne beschädigte Trennzeichen.
- [ ] Alle Bilder verfügen über aussagekräftigen Alt-Text für Barrierefreiheit.