Using Antora to Manage Complex Technical Documentation Websites
What's the best tool for managing technical documentation websites?
You've probably seen something like this on LinkedIn or Reddit. And the answer is, as always, 'it depends'.
For example, this site is run on Docusaurus, which is pretty easy to setup and maintain. It also works very nicely with Git and our web hosting provider, so for a relatively simple site, it's fine. I should add that you can Docusaurus is not just for lightweight document sites as it has quite a lot of rich features, themes, and a very active community. So, worth a peek if you're looking to get started.
However, there are a few things it doesn't offer. At least, not out of the box. This leads us to Antora.
What's the best tool for managing technical documentation websites?
You've probably seen something like this on LinkedIn or Reddit. And the answer is, as always, 'it depends'.
For example, this site is run on Docusaurus, which is pretty easy to setup and maintain. It also works very nicely with Git and our web hosting provider, so for a relatively simple site, it's fine. I should add that you can Docusaurus is not just for lightweight document sites as it has quite a lot of rich features, themes, and a very active community. So, worth a peek if you're looking to get started.
However, there are a few things it doesn't offer. At least, not out of the box. This leads us to Antora.
What is Antora?
Antora is a static site generator designed specifically for technical documentation. Created by the team behind AsciiDoc, it treats your document set as a collection of 'versioned content sources' rather than a traditional website structure. This allows you to setup "documentation sites" that can aggregate content from multiple repos, branches, and versions into a single website.
In other words, instead of pulling your documents from a single repo, which is what I'm doing here, you could ingest material from X number of repos and organize them in a seamless manner on the website.
Versioning is also one of its strong points. For instance, if you want to maintain multiple versions of your documentation simultaneously. You can do something like this in Docusaurus, btw.
Antora Use Cases
As mentioned above, while you can use tools like Docusaurus, Hugo, and Sphinx, from what I've seen its strength is in the following areas:
Multi-version Documentation Management
Once setup, you can maintain documentation for multiple product versions simultaneously. This allows you to pull content from different Git branches/repositories and publish them as separate versions in a single UI.
Distributed Documentation Teams
If you work on large projects or have distributed teams with multiple repos, you can aggregate the content from various sources into a single site while maintaining ownership and contribution workflows. While it does take time to configure, you'll see the gains in the long term.
Open Source Projects
It's a good fit for products that require community contributions, versioning, and integration with Git workflows.
Component-Based Architecture
For tech docs teams that work on require cross-referencing between different products and versions, you can use its component-based architecture to coordinate your content workflows.
For context, Antora's component-based architecture treats documentation as a collection of independent, reusable "components" rather than a monolithic website. As a result, each self-contained documentation unit can be mixed, matched, and assembled into different sites while maintaining their individual identity and versioning.
Each component has:
- Its own repository (or can share a repository with other components)
- Independent versioning (version 1.0, 2.0, etc.)
- Modular structure (modules containing pages, assets, and partials)
- Separate navigation and content organization
The following example provides a sample layout:
Company Documentation Site
├── API Gateway (Component)
│ ├── Version 3.0
│ ├── Version 2.1
│ └── Version 1.5
├── User Management System (Component)
│ ├── Version 2.2
│ └── Version 2.0
└── Analytics Dashboard (Component)
├── Version 1.8
└── Version 1.5
In this scenario, each component lives in its own Git repo, maintained by different teams, but appears as a unified documentation site to users.
Antora Limitations
There are a few limitations that you need to be aware of.
Learning curve
Compared to other tools, there is a bit of a learning curve. If you're familiar with static site generators, you'll understand how it's designed. However, if you're new to this area, it can be a bit tricky to get up and running. There's also a smaller community to help troubleshoot issues, which is unfortunate. Concepts (i.e. playbooks, components, modules, pages) can be overwhelming for tech writers coming from Flare/RoboHelp or less complex tech document tools.
AsciiDoc
Probably the main limitation is that you need to write (or migrate) your docs in AsciiDoc.
The team who created Antora felt that tech writers need a flavor of markdown with more advanced capabilities. While Markdown is fine for simple documentation, it has limitations for more complex technical material that requires advanced formatting, conditional text, and cross-referencing. However, I suspect this puts off many tech writers and developers who are used to writing in Markdown and may be reluctant to put time aside to skill up and migrate existing markdown.
Configuration Management
If you're new to SSGs, you may find the playbook configuration too complex for your sites. Troubleshooting issues regarding Antora's architecture and Git integration deter people from switching over.
Dynamic Features
I haven't explored this too much but from what I understand, it lacks built-in support for features such as user authentication, commenting systems, or implementing real-time content updates without additional tooling.
Deployment Complexity
Depending on your Git skill level, you may find its CI/CD pipelines and deployment strategies overly complex.
Plugin Ecosystem
Part of the reason, I use Docusaurus is because there is so much choice in terms of themes, plug-ins and community support. And it's all in markdown which everyone knows.
In contrast, Antora has a much smaller ecosystem of plugins and extensions.
Static Site Generator Comparison
The following table identifies the strengths and weakness of Antora and some of the leading SSGs.
| Feature/Aspect | Antora | Docusaurus | GitBook | VuePress/VitePress |
|---|---|---|---|---|
| Primary Focus | Multi-repo technical docs | Developer documentation | Team knowledge base | Vue.js ecosystem docs |
| Content Format | AsciiDoc only | Markdown + React/MDX | Markdown + blocks | Markdown + Vue |
| Learning Curve | Steep (new concepts + AsciiDoc) | Moderate (familiar React patterns) | Easy (WYSIWYG + Markdown) | Moderate (Vue knowledge helpful) |
| Multi-Version Support | Excellent (built-in, sophisticated) | Good (built-in versioning) | Limited (manual organization) | Manual implementation required |
| Multi-Repository | Native support (core feature) | Single repo only | Single workspace model | Single repo focus |
| Cross-References | Powerful (cross-component/version) | Basic (within single repo) | Good (within workspace) | Basic linking |
| Content Reuse | Advanced (includes, partials, attributes) | Limited (MDX components) | Basic (snippets, templates) | Limited (Vue components) |
| Team Collaboration | Excellent (distributed teams, Git-native) | Good (GitHub integration) | Excellent (real-time editing) | Good (Git-based) |
| Setup Complexity | High (playbooks, components, modules) | Low (npm create, config file) | Very low (web interface) | Low (Vue CLI or manual) |
| Build Performance | Can be slow (multi-repo aggregation) | Fast (optimized for speed) | Fast (cloud-based) | Very fast (Vite/modern tooling) |
| Theming/Customization | Limited themes, complex customization | Many themes, React-based custom | Limited (premium plans for custom) | Flexible (Vue-based theming) |
| Plugin Ecosystem | Small, specialized | Large, active community | Growing but limited | Good (Vue ecosystem) |
| Search Integration | Good (Lunr, external options) | Excellent (Algolia built-in) | Excellent (built-in) | Good (built-in + external) |
| Hosting Options | Flexible (any static host) | Flexible (Netlify, Vercel, etc.) | Managed hosting included | Flexible (any static host) |
| Community Size | Small, niche | Large, active (Facebook/Meta) | Large, growing | Medium (Vue community) |
| Documentation Quality | Comprehensive but complex | Excellent, beginner-friendly | Excellent, user-friendly | Good, Vue-focused |
| Mobile Experience | Good (responsive default theme) | Excellent (optimized) | Excellent (native apps) | Good (responsive) |
| Real-time Features | None (static only) | Limited (comments via plugins) | Real-time editing, comments | None (static only) |
| Content Management | Git-only (technical users) | Git-based (some CMS integrations) | Web-based editor | Git-based |
| Internationalization | Good (attribute-based) | Excellent (built-in i18n) | Good (multi-language spaces) | Good (Vue i18n integration) |
| Cost | Free (open source) | Free (open source) | Free tier limited, paid plans | Free (open source) |
Decision Framework
Choose Antora if:
- Multi-repository documentation is essential
- Team can invest in learning AsciiDoc
- Large-scale documentation challenges
Choose Docusaurus if:
- Single repository setup is sufficient
- Developer-focused documentation
- Need proven, widely-adopted solution
Choose GitBook if:
- Non-technical team members need to contribute
- Real-time collaboration is important
- Managed solution preferred over self-hosting
Choose VuePress/VitePress if:
- Build speed is critical
- Flexible theming requirements
- Technical team comfortable with Vue
One last thing
If you're running a relatively small tech document team with a single product, I'd suggest looking at tools, such as Docusaurus, Hugo, Sphinx, and Github Pages. This will allow you get started with publishing your tech docs.
Once comfortable with the process, you can then look at more complex workflows.
In the coming weeks, I'll go into more depth about how to setup a tech document website, tool usage, metrics and common pitfalls to avoid.
As always, drop me a line if you'd like to know more. My inbox is always open.