How to integrate 3rd party MDX content into Docs given the undefined startup order of plugins?

[ilg-ul]

After migrating all my project websites to Docusaurus, I wanted to take the final step and migrate the C/C++ reference pages as well.

These reference pages are generated using a third-party tool (Doxygen), which produces a set of XML files. To integrate them with Docusaurus, I wrote a plugin (docusaurus-plugin-doxygen) that parses the XML files and generates MDX files compatible with Docusaurus. You can see an example of the generated documentation on the µTest++ project website.

The docusaurus-plugin-doxygen plugin adds a CLI command (generate-doxygen) to Docusaurus, which generates the MDX files in /docs/api, as well as the sidebar and top menu bar entries. This setup works well and has been reliable.

However, for convenience, I wanted a tighter integration—specifically, to have the MDX generation run automatically when Docusaurus starts.

A fully standalone solution would generate the docs and use addRoute(), but this would require duplicating much of the logic already present in the Docs plugin, and is not practical.

Instead, I chose to generate the MDX files under /docs and let the Docs plugin handle them.

Unfortunately, I couldn’t find a straightforward way to ensure that docusaurus-plugin-doxygen runs before plugin-content-docs.

The only reliable workaround I found was to wrap both the Docs and Doxygen plugins in a new plugin, invoking their loadContent() methods in the required order. This approach works, but the code is somewhat complex and requires additional logic to separate plugin options.

• https://github.com/xpack/docusaurus-plugin-doxygen/tree/master/wrappers

While functional, I’m not entirely satisfied with this solution.

---

The core issue is the undefined startup order of plugins, due to their parallel initialization.

Are there any plans to improve this?

For example allowing plugins to declare dependencies so that they are initialised in the correct order?

Alternatively, could the order in which plugins are listed in the configuration be respected, perhaps by introducing a preLoadContent() hook (similar to validateOptions()), and ensuring these hooks run sequentially rather than in parallel?

[ilg-ul]

@slorber, any suggestions on how to better integrate content generated by 3rd party tools?

As it looks now, since there is no way to guarantee that a plugin is initialised before the docs/blog plugins that consumate this content, and writing a wrapper is not exactly nice, the only reasonable solution is to keep everything outside Docusaurus.