Best Practices: Handling Images in Docs-as-Code with AsciiDoc
Discover strategies for embedding and organizing images in a docs-as-code workflow with AsciiDoc and adoc Studio.
Embedding and managing images in a docs-as-code workflow can feel like navigating a maze. The approach you choose can significantly affect your repository’s size, structure, and overall maintainability.
Recently, a discussion in the Write the Docs community highlighted diverse strategies and tools for managing graphical assets. Let’s dive into these ideas and see how they fit into an AsciiDoc environment.
Options for Managing Graphical Assets
Handling images boils down to two key aspects: where to store them and how to organize them. Here's an overview based on the insights from the community:
1. Centralized vs. Distributed Storage
Centralized Storage: Many contributors recommend maintaining all assets in a dedicated
assets/directory, possibly with subfolders for better organization. This ensures all files are easy to locate and keeps your repository’s structure predictable.External Hosting: Tools like Cloudinary or similar platforms are excellent for hosting assets externally. They reduce the burden on your repository size and offer robust media management features.
2. Git Large File Storage (Git LFS)
For teams working with binary files like images or videos, Git LFS is a lifesaver. It keeps your main repository lightweight by replacing large files with pointers and storing the files externally. Several contributors in the thread vouched for this solution to manage growing repo sizes effectively.
3. Source File Versioning
A significant challenge is managing the source files of assets (e.g., the original diagrams or design files). Contributors highlighted the importance of storing these source files alongside the final exported images, ideally in the same system as your docs, ensuring they remain accessible and version-controlled.
4. Automation and Path Management
Automating repetitive tasks like screenshot generation or diagram updates saves time and ensures consistency. Using tools like PlantUML for diagrams-as-code or leveraging path autocomplete plugins (e.g., Path Autocomplete) simplifies referencing assets across complex repositories.
Leveraging AsciiDoc for Image Management
AsciiDoc provides a straightforward and flexible way to embed images, making it a favorite for docs-as-code workflows. Here's how to effectively manage images with AsciiDoc:
Embedding Images
AsciiDoc’s syntax makes it easy to include images:
image::assets/diagrams/example-diagram.png[Diagram Title, width=600, align=center]
You can customize the attributes (width, align, alt text) to fit your needs. A clear folder structure, like an assets/directory, ensures this process is smooth.
Managing Dynamic Content
For versioning or configuration-specific assets (e.g., different diagrams for various product versions), AsciiDoc’s conditional processing features let you include the right assets dynamically.
ifdef::productversionA[]
image::assets/productA/diagram.png[Product A Diagram]
endif::[]
Linking External Assets
If you’re using an external hosting service, AsciiDoc supports linking directly to URLs:
image::https://cloudinary.com/example/image.png[Hosted Image, width=800]
Why adoc Studio is Your Go-To for AsciiDoc
When it comes to managing images in AsciiDoc, having the right tool can make all the difference. That’s where adoc Studio steps in. With features like:
2. adoc Coach: Your Built-In Syntax Guide
Lost in syntax? Just press ESC. The adoc Coach instantly suggests attributes, macros, and commands, making AsciiDoc feel effortless. It’s like having an expert by your side, ready to help.
3. Unified Styles for HTML and PDF
Switch between HTML and PDF output without juggling separate stylesheets. With adoc Studio, you use one style sheet for all formats, saving time and ensuring consistent branding across your documents.
4. No More Terminal Troubles
Complex scripts? Gone. adoc Studio simplifies multi-target publishing, letting you manage variations and outputs with just a few clicks. Skip the coding headaches and focus on creating.
