Markdown-Konventionen

Kanonische Referenz für Form und Formatierung von Markdown in jedem verfassten .md- und .mdx-Artefakt. Die Zusammenfassung im Abschnitt „Conventions“ von CLAUDE.md ist die Inline-Deklaration; diese Seite ist die eigenständige Referenz, die nachgelagerte Mitwirkende zitieren.

---

1. VarianteCopy Anchor Link

GitHub-Flavored Markdown (GFM) ist die Host-Variante. Jedes Artefakt wird in der Weboberfläche von GitHub, auf der Fumadocs-Dokumentationssite und in gängigen Markdown-fähigen Editoren korrekt gerendert.

2. ÜberschriftenhierarchieCopy Anchor Link

Ein H1 pro Datei. Nachfolgende Überschriften steigen monoton ab (H2 → H3 → H4), ohne Ebenen zu überspringen. Überschriften in Satzschreibung; keine GROSSBUCHSTABEN, kein Title Case Für Jedes Einzelne Wort. Das H1 trägt den Haupttitel des Dokuments. Auf einer Seite der Dokumentationssite wird der Frontmatter-Wert title als H1 gerendert und ist der Anker der Seite in der Navigation der Dokumentationssite; der Seitentext beginnt daher bei H2.

3. CodeblöckeCopy Anchor Link

Umzäunte Codeblöcke deklarieren ihre Sprache (```python, ```bash, ```yaml, ```json, ```mermaid). Blöcke ohne Tag unterdrücken die Syntaxhervorhebung und signalisieren Drift beim Verfassen; die markdownlint-Regel MD040, konfiguriert in .markdownlint.json, erzwingt das Sprach-Tag.

4. Interne LinksCopy Anchor Link

Interne Querverweise verwenden Pfade ab der Site-Wurzel (z. B. [Authorship header](/docs/reference/authorship-header)). Bloße repository-relative Pfade mit einer .md/.mdx-Endung (/docs/foo.md) und vollständige URLs auf dasselbe Repository (https://github.com/ahmed-g-gad/apothem/blob/main/...) werden für Links innerhalb der Site vermieden, weil sie Umbenennungen von Seiten und Umstrukturierungen von Abschnitten schlecht überstehen.

Diese /docs/...-Pfade ab der Site-Wurzel — und die Form /<locale>/docs/... für die Nicht-Standard-Locales der Kohorte — löst der Validator link-check gegen die Seitenmenge auf der Festplatte unter site/content/docs/ auf: /docs/a/b wird auf site/content/docs/a/b.mdx oder den Ordnerindex site/content/docs/a/b/index.mdx abgebildet, und die Locale-Form wird unterhalb des Teilbaums site/content/docs/<locale>/ abgebildet. Ein Link auf eine entfernte oder umbenannte Route löst sich zu keiner der beiden Dateien auf und wird von link-check, einem beratenden Matcher, der den Lauf nicht fehlschlagen lässt, als tote Route (ein für Benutzer sichtbarer 404) gemeldet (siehe §6).

Externe Links auf veränderliche Refs (main, master, latest, HEAD) werden auf Commit-SHAs oder Release-Tags festgelegt, wann immer die Stabilität des verlinkten Inhalts wichtig ist; volatile Verweise werden mit einem angrenzenden {/* volatile */}-Kommentar als solche dokumentiert.

5. Autorschafts-HeaderCopy Anchor Link

Jedes Markdown-Artefakt (mit den unter src/apothem/schemas/header-exceptions.txt aufgezählten Ausnahmen) trägt den kanonischen Autorschafts-Header, die einzelne Zeile SPDX-License-Identifier: MIT, in der Kommentarvariante seines Dateityps gemäß Autorschafts-Header: ein HTML-Kommentar bei .md-Dateien und ein {/* ... */}-Kommentar bei .mdx-Dateien. Ohne Frontmatter ist die Header-Zeile Zeile 1. Mit YAML-Frontmatter bleibt das Frontmatter bei Byte 0, und die Header-Zeile folgt auf das schließende ---.

6. ValidatorenCopy Anchor Link

Der Pre-Commit-Hook markdownlint in .pre-commit-config.yaml führt markdownlint-cli mit der Regelrichtlinie in .markdownlint.json aus und erzwingt den Großteil der Regeln aus §§1–4. Der Markdown-Lint-Workflow führt bei jedem Push auf main und bei jedem Pull Request, der Markdown-Dateien ändert, denselben Hook in CI aus. CI prüft daher mit der Version, die der Hook festlegt. Die Richtlinie schaltet MD013 (Zeilenlänge), MD033 (Inline-HTML) und MD041 (Überschrift in der ersten Zeile) ab. Sie schaltet außerdem MD038 ab, weil das kanonische Options-Label-Postfix (Recommended) sein führendes Leerzeichen innerhalb eines Code-Spans behält, sowie MD060, weil kein Tabellenspalten-Stil die Tabellen mit kompakten Zellen und enger |---|-Trennzeile akzeptiert, die der Korpus verwendet. MD024 prüft nur Geschwister-Überschriften, sodass die Überschriften Added, Changed, Fixed und Security, die jedes Release in CHANGELOG.md wiederholt, die Prüfung bestehen. Die Begründung jeder Entscheidung steht neben dem Hook. Der Hook überspringt die Testfixture-Bäume tests/fixtures/, tests/conformity/, tests/conformity-scenarios/fixtures/ und tests/scripts/inject-header/fixtures/, deren Bytes die Tests festlegen. Außerdem überspringt er plugins/claude-code/, das python scripts/dev/assemble_plugin_tree.py aus src/apothem/ erzeugt: Jeder nummerierte Schritt eines Befehls wird zu einer eigenen Datei, sodass die Liste einer Schrittdatei bei ihrer Schrittnummer beginnt. Die Quellen unter src/apothem/ werden geprüft; ein Befund im Plugin-Inhalt wird daher dort behoben und der Plugin-Baum neu erzeugt.

Der file-header-grep in src/apothem/conformity/file_header_grep.py prüft §5. Der Validator link-check in src/apothem/conformity/link_check.py prüft die Disziplin der Linkauflösung aus §4 — er löst relative Links gegen das Verzeichnis der Quelldatei und Site-Routen der Form /docs/... (und /<locale>/docs/...) gegen die Seitenmenge von site/content/docs/ auf und markiert jeden Link, der sich zu keiner Seite auf der Festplatte auflöst. Beide sind beratende Matcher pro Write. Sie laufen im Pre-Commit-Hook conformity-corpus-perwrite und im Job corpus-perwrite-gate des Conformity-Workflows in .github/workflows/conformity.yml, und an beiden Stellen melden sie Befunde, ohne den Lauf fehlschlagen zu lassen. Das python -m apothem.conformity.gate --all . --strict des CI-Qualitätsjobs in .github/workflows/ci.yml deckt nur die eigenständigen Validatoren ab und führt daher keinen der beiden aus.