Best Practices für Bilder in Markdown

Dieser Leitfaden behandelt Bilder in Markdown und zeigt, wie sich Bilder in Repositories, Dokumentationsseiten und Exporten zugänglich und zuverlässig halten. Ziel ist kein beliebiger Screenshot, sondern ein lesbares, zur Markdown-Quelle rückverfolgbares und wiederholt publizierbares Asset.

PNG hält Text, Code, Tabellen und dünne Diagrammlinien scharf. JPEG kann bei fotografischen Hintergründen kleiner sein, macht kleine Schrift aber weicher. PDF passt zu mehrseitigem Lesen, DOCX zu editierbaren Office-Abläufen. Das Format muss zum Zielkanal passen.

1. Vorbereiten. aussagekräftigen Alt-Text für die vermittelte Information schreiben.
2. Prüfen. stabile HTTPS-URLs oder auflösbare Repository-Pfade verwenden.
3. Exportieren. Referenzbilder, Titel, Größen und Dark-Mode-Kontrast im Zielrenderer testen.

Dieses kleine Beispiel zuerst in den Renderer einsetzen und Typografie sowie Abstände prüfen.

![Dashboard showing weekly signups](https://example.com/dashboard.png "Weekly signup dashboard")

![Architecture diagram][architecture]

[architecture]: https://example.com/architecture.svg "Service architecture"

CommonMark definiert den portablen Markdown-Kern. Tabellen, Task-Listen und manche Autolinks sind GFM-Erweiterungen und können anderswo abweichen. Mermaid und KaTeX sind eigene Syntaxen unterstützender Renderer. Der Zielkanal bleibt die maßgebliche Prüfung.

• Aussagekräftigen Alt-Text schreiben.
• Logische Überschriften und Lesereihenfolge sichern.
• Kontrast in hellen und dunklen Themes prüfen.
• Bild in tatsächlicher Anzeigegröße kontrollieren.
• Markdown-Quelle versionieren.
• Bei Änderungen neu exportieren statt Pixeltext zu flicken.

Zu kleine Schrift, zu breite Tabellen, unerklärte Abkürzungen, instabile Remote-Bilder und zu enger Beschnitt schaden. Identisches Rendering in jeder Engine darf nicht versprochen werden; Erweiterungen und Themes setzen Grenzen.

Die Grenzen dieses Updates wurden anhand folgender Primärquellen geprüft:

• https://spec.commonmark.org/current/
• https://docs.github.com/en/get-started/writing-on-github
• https://markdowntoimage.com/

MarkdownToImage öffnen und das Beispiel in Zielbreite und Ziel-Theme testen. Verwandte Abläufe: erster Leitfaden und zweiter Leitfaden.