What this post is about
- The necessity of a new, more efficient tech stack
- The technical architecture behind our documentation transformation
- Key improvements in speed, search capabilities and UX
- Benefits for both our development team and Zammad users
The Zammad documentation has undergone a comprehensive upgrade! We have completely revamped it, both visually and structurally, to make it easier for you to work with Zammad—whether you are a developer, administrator, or user.
Why We are Rebuilding our Documentation
Zammad’s documentation has long been a cornerstone of our open-source mission. Clear, well-structured, and publicly accessible, it helps teams get more out of Zammad every day.
For a long time, we’ve relied on Sphinx, a Python-based static site generator using reStructuredText to generate well-structured content across different media. The entire Zammad documentation was hosted on Read the Docs Community—a fantastic and free resource.
This setup served us well for years, but as both Zammad and our contributor base expanded, it became increasingly clear that our Python-based stack was no longer keeping up. Its popularity dwindled down as its complexity grew, and with it the dreaded ‘dependency hell’. Meanwhile, more modern, user-friendly alternatives emerged that promised better performance with less maintenance overhead—exactly what our growing community needed.
The Renaissance of Static Web
Over the past decade, static websites have seen an impressive revival. With the goal of efficiently delivering rarely updated content to an ever-growing audience, a plethora of Static Site Generators entered the scene—quickly embraced for their low hosting costs and lightning-fast load times.
In this evolving landscape, a natural balance has formed: Static sites have proven to be the perfect solution for use cases like software manuals and documentation. And, quite honestly, they’re just more enjoyable to work with—thanks to lightweight markup languages like Markdown, taking the center stage and decluttering our minds.
Embracing a Modern Tech Stack with Vue.js/Vite
For our desktop rewrite, we chose a modern tech stack: the Vue.js framework as the foundation and Vite as a fast and efficient bundling tool. Naturally, it made sense to look for a documentation solution within the same ecosystem—leveraging our team’s expertise to the fullest.
Enter VitePress—a platform that promised to do just what we wanted, so we gave it a shot. Built on the well-established VuePress, it provides out-of-box Markdown support and benefits from a strong community. We particularly liked the sleek default theme, which includes both light and dark modes—ensuring a comfortable reading experience, whether in daylight or in a dimly lit environment.
Structure That Organizes Itself
The structure of a static website is its backbone—it ensures fast and logical organization and quick access to information. Flat-file systems are perfect for this: simply drop a file into the right folder, and you’re done. While VitePress doesn't include this functionality by default, it can be easily added through community plugin. This architectural choice delivers multiple benefits.
The primary navigation can be automatically derived from the structure, along with the route paths that follow a clean URL schema.
Secondary navigation is natively supported and is based on the actual content of Markdown files. Gone are the days of the needed table of content directives, it just works™.
VitePress also supports frontmatter, the de facto standard for Markdown metadata. With just a handful of special keys, it's possible to control not only a page's appearance but also its position and presentation in the navigation. This creates exciting possibilities for future extensions and significantly enhances usability for both contributors and readers.
A Practical Solution for Multilingual Documentation
Making our documentation multilingual was initially a bit of a pain. While VitePress offers native support for multiple languages, its implementation is—let’s put it nicely—a bit clunky. All translated Markdown files need to be present in the correct structure from the start, which didn’t align well with our Weblate-based, community-driven translation platform.
The solution came in the form of a small but powerful Perl utility called po4a. It could still rely on source strings in gettext format, but could provide us with a reliable interim pre-build process that can prepare all the files we need.
This resulted in a satisfied requirement: only the source content in English had to be modified, the rest would be automatically translated and pre-generated before the build. The downside is that some of the Markdown code still manages to seep into our translation sources, but we deemed it an acceptable compromise.
For you as a user, this means more consistent translation quality, more available languages, and documentation that’s accessible worldwide.
Automated Screenshots: Visual Documentation That Never Grows Stale
Zammad’s documentation has always been rich in visuals—combining plain text instructions with animations and screenshots to illustrate each step. However, maintaining these images was tedious: Even minor UI changes could necessitate updates to numerous images across our guides.
So, we thought: Why not automate it? Since the Zammad app already runs as a Docker Compose stack, we can spin up the latest app version locally at any time. And because this system can be deterministically populated with sample data, all we needed was a tool to generate the required screenshots automatically.
That’s where Cypress came in. Originally built for automated testing, this platform offers a powerful scripting system for on-demand screenshots. With a few Zammad-specific extensions, we built a setup that simply runs an end-to-end test script—et voilà, all necessary images are generated instantly.
The result transforms our workflow: no more manually updating individual screenshots, no more binary files cluttering the repository. Most importantly, users always see exactly what the current Zammad version looks like, eliminating confusion caused by outdated visuals.
CI/CD Pipeline: The Final Piece for Truly Automated Documentation
Finally, to top everything off, we implemented a CI/CD pipeline. This automated process takes care of several essential tasks, ensuring our documentation is always up to date:
- Cloning the documentation repository
- Integrating the latest translations from Weblate
- Generating up-to-date screenshots
- Building the static documentation site
For deployment, we found that self-hosting offers the most control in the long run. However, this setup remains flexible—depending on needs. Fortunately, nowadays, many free hosting platforms are available, including GitHub, GitLab Pages, and Cloudflare Pages.
Zammad Docs 2.0 – What Do You Think?
We’re building this new documentation system with the community in mind—and that includes you. That's why we invite you to explore our new documentation and experience the difference firsthand. If you spot issues, have suggestions, or want to contribute new content, we encourage you to get involved.
You can open an issue in our GitHub Zammad repository , submit a pull request (or two), or join the translation effort on Weblate . The community will appreciate it!