Getting Started with doxygen2docusaurus
To accommodate the diverse requirements of its audience, this site provides distinct pages: User's Guide, Contributor's Guide and Maintainer's Guide. Each guide is tailored to ensure users can efficiently access the information and resources most relevant to their specific roles or requirements.
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 comprehensive 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 (builds require considerable time and memory consumption is very high), rendering it unsuitable as an exemplar 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 adheres to a continuous release approach, with updates deployed as development progresses.
Releases
A comprehensive list of releases may be found on the Releases pages.
Change log
The release notes and change log may be accessed within the repository's
CHANGELOG.md
file.
Support & feedback
For prompt support and to provide feedback, it is recommended to utilise GitHub Discussions.
For more detailed information, please visit 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. This information provides a comprehensive overview of significant modifications and is readily available 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 Licence, 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.
Enjoyed Using This Project? Please Let Us Know!
If you have found this project valuable, we would appreciate hearing from you! Here are some ways you can demonstrate your support:
- Donate: Every contribution, regardless of size, helps sustain the xPack . Your generosity maintains the development and ensures continued progress.
- Star the project on GitHub: Assist others in discovering our work by giving it a star — it truly makes a difference!
- Follow Us on X/Twitter: Stay informed about our latest updates, releases, and news by following our account.
Your support is greatly appreciated and motivates us to continue improving!