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“

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.
Semantische Eindeutigkeit: Die Symbole #, -, > sowie Inline-Code-Marker belasten das Kontextfenster nicht unnötig und geben dem Modell eine klare Karte der Gedanken-Hierarchie.
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“).
Versionskontrolle in Git: .md-Dateien sind reine Textdateien, weshalb Änderungen an Wissensdatenbanken oder Dokumentationen einfach über git diff nachvollziehbar sind.

Hinweis

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.

Hierarchie der Überschriftenebenen in Markdown und entsprechende HTML-Tags Збільшити

Hierarchie der Überschriftenebenen in Markdown und entsprechende HTML-Tags

Überschriftenebene	Markdown-Syntax	HTML-Äquivalent	Typische Verwendung
Ebene 1	`# Überschrift`	`<h1>`	Titel des gesamten Artikels oder Dokuments (nur einmal pro Seite)
Ebene 2	`## Überschrift`	`<h2>`	Hauptabschnitte und zentrale Module des Themas
Ebene 3	`### Überschrift`	`<h3>`	Unterabschnitte, Schritte in Anleitungen, einzelne Tools
Ebene 4	`#### Überschrift`	`<h4>`	Detaillierung von Unterpunkten, Parameter, Hinweise
Ebene 5	`##### Überschrift`	`<h5>`	Kleine technische Fußnoten
Ebene 6	`###### Überschrift`	`<h6>`	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.

Vergleich korrekter und inkorrekter Schreibweise von Überschriften Збільшити

Vergleich korrekter und inkorrekter Schreibweise von Überschriften

Warnung

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 <h1>-Tag enthalten.

3. Textformatierung: Fett, Kursiv, Durchgestrichen und Sonderzeichen

Inline-Hervorhebungen helfen dabei, die Aufmerksamkeit auf Schlüsselbegriffe und Konzepte zu lenken.

Syntax zur Kursivsetzung von Text in Markdown Збільшити

Syntax zur Kursivsetzung von Text in Markdown

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

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 ```bash npm run build

terminal

``` > [!NOTE] > Переконайтеся, що змінні оточення у файлі `.env` налаштовані правильно перед запуском.

2. Перевірте вихідний каталог dist/.

terminal

--- ## 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:** `<https://github.com>` oder `<support@example.com>` - **Bild:** `[Beschreibung des Bildes für Barrierefreiheit](/images/diagram.webp "Tooltip")` - **Klickbares Bild-Link:** `[![Alt-Text](/images/btn.webp)](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): ![Korrekte Codierung von Leerzeichen und runden Klammern in URL-Links](/api/guides-media/automation/markdown-format-guide-for-ai/images/markdown-format-guide-for-ai-extra-03.webp) ```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})`; }

Wichtig

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.

Sonderzeichen der Markdown-Syntax, die mit einem Backslash escaped werden können Збільшити

Sonderzeichen der Markdown-Syntax, die mit einem Backslash escaped werden können

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 (<div>, <table>) 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.