Docs: configuration guide content on new tools

[agjohnson]

In #10301 we brought up the idea of adding examples for unsupported tools like
Pelican, Docusaurus, and custom builders. For now, we've passed on these
examples as this guide is intended for novice users and build.commands is
still quite beta:

• Hosting features don't currently all work, though we are changing that with the addons JS work
• Many configuration file options stop functioning when using build.commands
• These users are mostly on their own and we don't have control over the build process
• Build customization is still communicated as beta

We should still point advanced/expert users towards these solutions, but our
configuration guide is targeting a more novice user. The UX issues with
unsupported tools is going to show a lot of our rough edges, and novice users
will have a bad experience right away.

Eventually, we should show support for more tools in our introductory guide
(and application), once they are better supported. This means at least our
hosting features work for these tools, via addons JS.

It might also include waiting for support for build.jobs.build overrides.
Otherwise, we are introducing the configuration file and it's options, and then
immediately pointing the user towards an option that disables much of the
configuration file.

We could also choose to do something similar to the configuration guide, but
specific to unsupported tools and expert users. We currently put these examples
in the build customization docs, but could make a specific page "How to use
unsupported tools", with copious warnings.

[ericholscher]

I'd be 👍 on a short howto around using docasaurus using the existing example, so we can have some SEO pointing to it, and see if people are landing on it? Might be a good way to reuse the content we already wrote in a minimal place, and it can be updated later, but already starting to rank on Google?

[agjohnson]

True, we could start some specific guides like "How to user Docusaurus on Read the Docs". I was describing a page to accumulate advanced/expert examples, but that pattern wouldn't help us as much with SEO.

If we can get some of the examples out of the build customization guide, and into either individual guides or a guide intended for expert users and multiple unsupported tools, both would be a good step forward.

[humitos]

@agjohnson

Eventually, we should show support for more tools in our introductory guide (and application), once they are better supported. This means at least our hosting features work for these tools, via addons JS.

We are already there, I'd say since most of our addons are already working 😉

If we can get some of the examples out of the build customization guide, and into either individual guides or a guide intended for expert users and multiple unsupported tools, both would be a good step forward.

I think we are in a better position now to start writing the content for these guides in our own documentation and promoting other doctools more while showing the integrations working 🚀

@ericholscher

using docasaurus using the existing example, so we can have some SEO pointing to it, and see if people are landing on it? Might be a good way to reuse the content we already wrote in a minimal place, and it can be updated later, but already starting to rank on Google?

It's not a how-to, but it's content showing a Docusaurus example that probably benefits SEO: https://about.readthedocs.com/docs-as-code/

[ericholscher]

Yea, I think building doc howtos based on these original examples is a great next step. It doesn't need to be much more complex than just walking folks through the steps implied by the config file 💯

[humitos]

We a documentation page with example projects that could be useful when working on this issue: https://docs.readthedocs.io/en/stable/examples.html

[humitos]

This is issue is superseded by #11187 and I think it can be closed.