What do you think about a docusaurus-plugin-doxygen?

[ilg-ul]

Do you know of any work on a plugin to integrate Doxygen reference pages into Docusaurus?

I recently migrated one of my TypeScript projects to Docusaurus and used docusaurus-plugin-typedoc for the TypeDoc integration (the result is at https://xpack.github.io/logger-ts/).

Next I want to migrate some C/C++ projects sites to Docusaurus, and I am looking for a similar solution for Doxygen.

Google did provide some links to projects converting the Doxygen XMLs to plain markdown, but nothing related to Docusaurus.

If there is no such a plugin available, would anyone else be interested in one? The idea would be to use Doxygen to output XMLs, and use the plugin to convert them to Docusaurus .mdx pages (similarly to the TypeDoc plugin which generates .md pages).

Any thoughts on this?

[slorber]

I don't know anything about Doxygen.
This request doesn't come often but I've seen it mentioned a few times in the past.
Search the repo to find people that have expressed interest for a plugin:
https://github.com/search?q=repo%3Afacebook%2Fdocusaurus+Doxygen+&type=issues

[ilg-ul]

I checked those links, but none is relevant.

[slorber]

This is the most information I have about Doxygen

[ilg-ul]

Apart from the Doxygen specifics, which are not relevant at this point, what do you think about a plugin that, using some input files generated by another tool in a previous external step, generates some .mdx files in a folder below docs, each time docusaurus is invoked for build or start?

Is this something that the existing Docusaurus API fully supports, and the documentation provides enough details?

Or, in other words, is this a reasonable approach?

[ilg-ul]

Or, to rephrase it, is there a better approach? For example skipping creating physical .mdx files and going directly to using something like addRoute()?

[slorber]

Apart from the Doxygen specifics, which are not relevant at this point, what do you think about a plugin that, using some input files generated by another tool in a previous external step, generates some .mdx files in a folder below docs, each time docusaurus is invoked for build or start?

Why does it have to be a Docusaurus plugin? If there's already an external step involved, the mdx generation can also happen outside Docusaurus. The external step becomes Doxygen + your custom nodejs script.

Or, to rephrase it, is there a better approach? For example skipping creating physical .mdx files and going directly to using something like addRoute()?

We currently don't have a concept of "virtual module" where you can emit code from the Node.js side without writing real files to the file system.

However, not everything has to be a module: you can also provide the content as a serializable structure (for example, JSON) that you inject into an existing component and render that structure through React. This JSON can be an AST, for example Markdown:

addRoute({
  component: "@theme/MyMarkdownRenderer",
  props: {
    markdownAST: toMarkdownAST("# Title"),
  }
})

Now this is something you can do while implementing your own plugin. But what I understand here is that you want to reuse the docs plugin code, and it doesn't offer you a way to do that, so you'd have to build your own plugin for that.

[ilg-ul]

the mdx generation can also happen outside Docusaurus.

Indeed.

But what I understand here is that you want to reuse the docs plugin code, and it doesn't offer you a way to do that, so you'd have to build your own plugin for that.

As you suggested, I decided to place the API Reference pages as /docs/api/. If I understand the Routing page right, this means that the docs plugin will handle those nested routes, possibly with multiple versions, so, yes, I guess I want to reuse the docs plugin code.

We currently don't have a concept of "virtual module" where you can emit code from the Node.js side without writing real files to the file system.

I could not find the definition of virtual module in the documentation. :-(

My preliminary plan was to use loadContent() to parse the input files into some internal structures, then on contentLoaded() to do some magic, possibly with createData(), create a lot of internal routes for all API pages and finally addRoute({path: 'api', component: '@thee/DocsRoot', routes:... }).

Isn't this realistic? The inspiration was a Docusaurus plugin that does a similar thing but for TypeDoc:

• https://github.com/milesj/docusaurus-plugin-typedoc-api/blob/b069bc730f29af206c42684c09cdeb6b39d50f00/packages/plugin/src/index.ts#L406

[slorber]

I could not find the definition of virtual module in the documentation. :-(

This is normal because as I said, there's no concept of virtual module. We don't document what doesn't exist.

The inspiration was a Docusaurus plugin that does a similar thing but for TypeDoc

I'm not particularly familiar with this plugin's code but it looks inspired from the official docs plugin, somehow a fork of it. It reuse some of the existing theme components we built for docs, which is possible if you provide them with the data they expect.

Yes, you can take it as inspiration, it is realistic.

[ilg-ul]

Yes, you can take it as inspiration, it is realistic.

Great, I'll consider this in the near future.

Thank you!