Bilder in AsciiDoc einbinden: Best Practices für Docs-as-Code
Strategien zur Einbettung und Organisation von Bildern in einem Docs-as-Code-Workflow mit AsciiDoc und adoc Studio
Das Einbetten und Verwalten von Bildern in einem Docs-as-Code-Workflow erfordert klare Strategien, da Ihre Wahl die Größe, Struktur und Wartbarkeit des Repositories direkt beeinflusst.
Kürzlich hat eine Diskussion in der Write the Docs-Community verschiedene Strategien und Tools für den Umgang mit grafischen Ressourcen hervorgehoben. Tauchen wir in diese Ideen ein und sehen, wie sie in einer AsciiDoc-Umgebung umgesetzt werden können.
Optionen zur Verwaltung von grafischen Ressourcen
Der Umgang mit Bildern lässt sich auf zwei wesentliche Aspekte reduzieren: Wo werden sie gespeichert? und Wie werden sie organisiert? Hier ein Überblick basierend auf den Erkenntnissen der Community:
1. Zentralisierte vs. verteilte Speicherung
Zentralisierte Speicherung: Viele Teilnehmer empfehlen, alle Ressourcen in einem dedizierten
assets/-Verzeichnis zu speichern, idealerweise mit Unterordnern für eine bessere Organisation. Dies erleichtert die Auffindbarkeit und sorgt für eine vorhersehbare Struktur des Repositories.Externe Hosting-Dienste: Tools wie Cloudinary oder ähnliche Plattformen eignen sich hervorragend zum externen Hosting von Ressourcen. Sie reduzieren die Belastung der Repository-Größe und bieten robuste Funktionen zur Medienverwaltung.
2. Git Large File Storage (Git LFS)
Für Teams, die mit Binärdateien wie Bildern oder Videos arbeiten, ist Git LFS eine enorme Erleichterung. Es hält das Haupt-Repository schlank, indem es große Dateien durch Zeiger ersetzt und die Dateien extern speichert. Mehrere Diskussionsteilnehmer lobten diese Lösung, um wachsende Repositories effektiv zu verwalten.
3. Versionierung von Quelldateien
Eine besondere Herausforderung besteht darin, die Quelldateien von Ressourcen (z. B. die ursprünglichen Diagramme oder Designdateien) zu verwalten. Die Community betonte die Bedeutung, diese Quelldateien zusammen mit den final exportierten Bildern zu speichern, idealerweise im gleichen System wie die Dokumentation, um sie zugänglich und versioniert zu halten.
4. Automatisierung und Pfadverwaltung
Die Automatisierung von sich wiederholenden Aufgaben wie der Screenshot-Erstellung oder dem Aktualisieren von Diagrammen spart Zeit und sorgt für Konsistenz. Tools wie PlantUML für diagrammbasierte Code-Dokumentation (diagrams-as-code) oder Plugins wie Path Autocomplete vereinfachen die Referenzierung von Ressourcen in komplexen Repositories.
AsciiDoc nutzen, um Bilder zu verwalten
AsciiDoc bietet eine einfache und flexible Möglichkeit, Bilder einzubetten, was es zu einem Favoriten für docs-as-code Workflows macht. So können Sie Bilder effektiv mit AsciiDoc verwalten:
Bilder einbetten
Die Syntax von AsciiDoc macht das Einfügen von Bildern leicht:
image::assets/diagrams/example-diagram.png[Diagram Title, width=600, align=center]
Sie können Attribute wie Breite, Ausrichtung oder Alt-Text (width, align, alt text) nach Bedarf anpassen. Eine klare Ordnerstruktur wie assets/erleichtert diesen Prozess erheblich.
Dynamische Inhalte verwalten
Für versionierte oder konfigurationsspezifische Ressourcen (z. B. unterschiedliche Diagramme für verschiedene Produktversionen) ermöglichen die konditionalen Funktionen von AsciiDoc das dynamische Einbinden der passenden Ressourcen:
ifdef::productversionA[]
image::assets/productA/diagram.png[Product A Diagram]
endif::[]
Externe Ressourcen verlinken
Wenn Sie einen externen Hosting-Dienst nutzen, unterstützt AsciiDoc direkte Verlinkungen zu URLs:
image::https://cloudinary.com/example/image.png[Hosted Image, width=800]
Warum adoc Studio Ihr perfektes Tool für AsciiDoc ist
Beim Verwalten von Bildern in AsciiDoc macht das richtige Tool den entscheidenden Unterschied – und hier kommt adoc Studio ins Spiel. Mit Funktionen wie:
1. adoc Coach: Ihr eingebauter Syntax-Guide
Verloren in der Syntax? Drücken Sie einfach ESC. Der adoc Coach schlägt sofort Attribute, Makros und Befehle vor und macht AsciiDoc mühelos. Es ist, als hätten Sie einen Experten immer an Ihrer Seite.
2. Einheitliche Styles für HTML und PDF
Wechseln Sie zwischen HTML- und PDF-Ausgaben, ohne separate Stylesheets zu verwalten. Mit adoc Studio verwenden Sie ein einziges Stylesheet für alle Formate. Das spart Zeit und sorgt für konsistente Markenpräsenz.
3. Keine Terminal-Probleme mehr
Komplexe Skripte? Nicht nötig. adoc Studio vereinfacht das Publizieren für mehrere Zielplattformen und ermöglicht die Verwaltung von Variationen und Ausgaben mit nur wenigen Klicks. Konzentrieren Sie sich auf das Erstellen, nicht auf das Programmieren.
