[abought]

This looks interesting!

In the past, I've been a big fan of automatic documentation generators (jsdoc, openapi, etc), because keeping a markdown file full of function names and arguments up to date by hand was painful- but I don't like that those systems have little room for prose content like guides or tutorials.

Does Docusaurus support both types of information? The examples I've browsed so far seem to involve hand-edited API docs (example: Babel - https://raw.githubusercontent.com/babel/website/main/docs/pa...). I'd love to see a system that supported building and showing API docs and prose guides in one site, or at least allowed automated cross-linking in a way that could be kept up to date.

[vaughan]

Combining TypeScript's API Extractor (Microsoft) with Docusaurus is great.

You can mix guides/tutorials with generated API docs.

For example, I really like having simple API docs in the `readme.md` file, but then also in-depth docs elsewhere.

MDX + remark really let you do anything you want. It's the ultimate documentation stack.

[1]: https://api-extractor.com/pages/setup/generating_docs/

[acemarke]

Do you have any good examples of this in action and showing configuration?

I've been wrestling with this as we work on finalizing the new "RTK Query" APIs for Redux Toolkit. I'd love to have some auto-generated TS API docs embedded in the hand-written Markdown pages. My biggest questions are things like how to present reasonable details on some of our typedefs, which can get insanely complex and readers don't need to see all the internal sub-types.

I recently opened up an RTK issue asking for suggestions on TS API ref integration:

https://github.com/reduxjs/redux-toolkit/issues/1046

[slorber]

You can embed doc generated by other tools in a Docusaurus site, as a plain page or an iframe. Some people embed Javadoc, OpenAPI or Redoc in Docusaurus.

You can also generate md to make that doc native. I've seen people generating docs from a GraphQL schema for example