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.
The doxygen2docusaurus project 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 your project's documentation site.
Features & Benefits
Professional documentation pages
The tool leverages Docusaurus's clean, modern interface to create visually appealing and professional-looking documentation pages.
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.
Customisable topic organisation
The tool enables grouping of API reference documentation by topics, which can be customised to suit your project's requirements. This feature enhances the organisation of documentation, making it easier for users to locate relevant information. Each topic page is organised into clear sections, with comprehensive indices for all sections displayed at the beginning of the page for quick 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 featuring reference pages generated by doxygen2docusaurus is the µTest++ project, which is a 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 first public release.
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!