[Idea] plugin documentation

[jonnydgreen]

I had an idea regarding the next iteration of the documentation (after the initial release) and curious to hear your thoughts!

Idea

It essentially revolves around this: are we able to make the distributed Mercurius plugin documentation directly available in the central mercurius docs portal rather than linking out? Is this something that is even wanted at this time?

Possible solution

My thought was the following:

• Register a plugin at dev time with the following:
  • URL to fetch from
  • Path to download to
  • Name
  • etc
• At build time, the docs for this plugin are fetched and built
• Docs deployed with all registered plugin documentation

Note, Docusaurus supports multi-repos (the same technique for versioning docs): https://docusaurus.io/docs/docs-multi-instance

Things to consider

• What if a plugins docs breaks the docusaurus build? How should this be handled? E.g. should we lock plugin docs to a commit for example?
• It's unlikely this would be done for every plugin, so is a mixed approach desirable?

[simoneb]

If done properly, it may work, but ultimately I think that decentralization works better here. I do agree though that a more consistent way to document plugins (and this is true also and especially for the broader fastify ecosystem) would be valuable, because there are large inconsistencies across plugins which give a feeling of fragmentation.

So, rather than centralizing the documentation, I would like to find ways to make the documentation more consistent.

[jonnydgreen]

Thanks for your input! I'll update the idea include some stuff on how to make the documentation more consistent across the board as well and include the decentralised approach so we have everything on the table - stay tuned! :)

In a decentralised model, I guess my only concern would be discoverability of plugins. Do you have anything in mind regarding this?