docusaurus-plugin-doxygen

A Docusaurus plugin to integrate the Doxygen reference pages into Docusaurus documentation sites.

This project relies on the ability of Doxygen to also generate the output in XML. The plugin parses these XML files and generates MDX files in the /docs/api/ folder.

Doxygen configuration

To enable Doxygen to generate the XML files, enable it in the Doxygen configuration file:

GENERATE_XML= YES

By default, the output is generated in the Doxygen folder, in an xml sub-folder, for example, if the Doxygen folder is located in the website folder, the XML files will be generated in website/doxygen/xml.

Plugin install

To install the plugin in the project website folder:

(cd website; npm install @xpack/docusaurus-plugin-doxygen react-markdown --save-dev)

or, during development:

(cd website; npm link @xpack/docusaurus-plugin-doxygen)

Docusaurus configuration

For Docusaurus to use the plugin, it must be added to docusaurus.config.js

const config: Config = {
  // ...
  plugins: [
    [
      '@xpack/docusaurus-plugin-doxygen',
      {
        doxygenXmlInputFolderPath: 'doxygen/xml',
        verbose: false,
        suggestToDoDescriptions: false
      },
    ],
  ],
};

If the Doxygen folder is located in a different location, update the doxygenXmlInputFolderPath property.

To ease running the conversion, add a npm script to package.json:

  "scripts": {
    "docusaurus": "docusaurus",
    "generate-doxygen": "docusaurus generate-doxygen",
    "start": "docusaurus start",
    ...
  }

To run the conversion, use:

npm run generate-doxygen

Sidebar

The plugin generates a separate sidebar for the Doxygen pages.

To add it to Docusaurus, edit the sidebars.ts file; add the following line in the header part to import the generated file:

import doxygenSidebarItems from './sidebar-category-doxygen.json';

Add a new property in the sidebars object:

const sidebars: SidebarsConfig = {

  docsSidebar: [
    // ...
  ],

  doxygenSidebar: [
    doxygenSidebarItems,
  ],
};

Top menu

The plugin also generates a dropdown menu to be used in the top bar.

To add it to Docusaurus, edit the docusaurus-config.ts file; add the following line in the header part to import the generated file:

import doxygenApiMenu from './docusaurus-config-doxygen-menu-dropdown.json'

Add the doxygenApiMenu to the navbar.items.

Memory usage

For very large sites, it is possible that the node process runs out of memory.

To increase the heap and/or the stack, invoke docusaurus via a command like:

node --max-old-space-size=8192 --stack-size=2048 ./node_modules/.bin/docusaurus generate-doxygen