Getting Started with doxygen2docusaurus
The site has a separate guide for each audience:
- the Installation Guide;
- the User's Guide;
- the Contributor's Guide;
- the Maintainer's Guide.
Doxygen is the industry standard for generating API documentation from annotated C/C++ source code.
Docusaurus is a modern documentation website generator that provides a clean, responsive, and user-friendly interface for creating documentation sites.
doxygen2docusaurus is a command-line tool that bridges the gap between Doxygen-generated API documentation and modern Docusaurus websites. It converts Doxygen XML output into CommonMark files optimised for Docusaurus, enabling seamless integration of comprehensive API reference documentation within project documentation sites.
Features & Benefits
High quality documentation pages
The tool leverages Docusaurus's clean, modern interface to generate visually appealing and professional-grade documentation pages. (The images are from the µTest++ project)
Enhanced navigation experience
To improve the user navigation experience, for each reference sub-site, the tool generates a dropdown menu for the top navigation bar and a sidebar. For each page, it also creates the headers necessary for the table of contents.
Flexible topic-based structure
Doxygen enables grouping of API reference documentation by topics, and doxygen2docusaurus prioritises rendering these topic pages with enhanced structural organisation. This functionality improves documentation accessibility, facilitating efficient information retrieval. Each topic page is systematically organised into distinct sections, with comprehensive indices presented at the beginning of each page to enable rapid navigation.
Streamlined documentation workflow
doxygen2docusaurus is a versatile CLI application that can be employed in virtually any scenario, from manual invocation to automated CI/CD environments, with the generated pages either forming part of the repository or being created dynamically during website publishing.
However, the recommended approach is to execute the tool on the development machine where the website is maintained, allowing the resulting CommonMark files to be seamlessly integrated into existing Docusaurus sites and stored within the project repository.
Whilst this approach requires additional repository space, the significant advantage lies in enabling straightforward tracking of documentation changes.
Installation
@xpack/doxygen2docusaurus is an npm package available from the npmjs.com public registry and may be installed via npm.
The most straightforward method to obtain the installation command is from the website's homepage. Simply hover the mouse over the command, and a copy button will appear on the right side. Click it to copy the command.
For detailed installation instructions, please visit the Installation Guide page.
Status
The @xpack/doxygen2docusaurus project is functional, but it is still young and may require further development and refinement.
Demo sites
During development, several sites were employed to test and validate the converter.
Doxygen website
The primary demonstration site is a replica of Doxygen's own website, which was originally divided into two separate sites: the user manual and the reference documentation. Both have been consolidated into a single Docusaurus site featuring two reference sub-sites.
The Doxygen replica site is publicly available in the xpack/web-doxygen repository, and the site is available at https://xpack.github.io/web-doxygen/.
LLVM API reference
The LLVM API reference is another example of a site that has been successfully converted using doxygen2docusaurus.
Unfortunately, the site is exceptionally large (20,000+ pages, 1GB+), and Docusaurus does not handle such large sites effectively (build times are considerable, and memory consumption is very high), making it unsuitable as a demonstration for a Docusaurus site.
The LLVM replica site is publicly available in the xpack/web-llvm repository.
µTest++ project
The first production-grade website to incorporate reference pages generated by doxygen2docusaurus is the µTest++ project, a comprehensive C++ unit testing framework.
tsdoc2docusaurus
The tsdoc2docusaurus project is a companion project that provides functionality to convert TSDoc reference pages to Docusaurus .md files.
Whilst it is less refined and not yet available as an npm package, it is largely functional and can be employed to document TypeScript projects that utilise TSDoc comments. The API pages of this website serve as an example of its output.
Release schedule
There are no scheduled releases; the project follows a continuous release model, with new versions published as development progresses.
Releases
The list of releases is available on the Releases page.
Change log
The release notes and the change log are in the
CHANGELOG.md
file of the repository.
Support and feedback
Use GitHub Discussions for support and feedback.
For more information, see the Help Centre page.
Compatibility notices
According to SemVer rules:
Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API.
The breaking changes introduced in each major release are documented in reverse chronological order. The details are in the respective release notes.
v1.x (2025-08-03)
The initial pre-release version, intended for internal testing and evaluation.
v2.x (2025-08-08)
The first public release. Several configuration variables have been renamed to better reflect their intended purpose, including navbarFilePath, navbarLabel, and listPagesAtTop.
Licence
Unless explicitly stated otherwise, the original content is distributed under the terms of the MIT License, with all rights reserved by Liviu Ionescu.
Credits
Special thanks to MacStadium for providing the Apple Silicon development infrastructure as part of their generous Free and Open Source Software programme.
Special thanks to the doxygen-awesome-css plugin for providing inspiration for the overall visual design of the pages.
Thanks to Shields IO for the badges and SVG REPO for the SVG icons.
Support the project
If you find this project useful, you can support it in the following ways: