Put docs under /docs, so 404 works

[huonw]

This moves the docs to be under /docs, rather than at the top level. For example:

Prose docs:

• old: https://docs.pantsbuild.org/2.18/docs/introduction/welcome-to-pants
• new: https://docs.pantsbuild.org/docs/2.18/docs/introduction/welcome-to-pants

Reference docs:

• old: https://docs.pantsbuild.org/2.18/reference/global-options
• new: https://docs.pantsbuild.org/docs/2.18/reference/global-options

This is mostly to fix #7 by working around facebook/docusaurus#9688. With this change, a URL like https://docs.pantsbuild.org/abc/xyz shows the 404 content. That said, is arguably nice to have everything in a defined little box (i.e. we've got a /blog box, a /community box, and now a /docs box).

This does have the downside of making URLs longer and somewhat repetitive, but it seems fine. 🤷‍♂️ If we hated the repetition we could choose different words (like /docs/2.18/guides/... for prose docs) or "silly" tricks with URLs, like /v/2.18/docs/... to be read like v2.18 (this doesn't work so well if we choose to also do unversioned URLs in future).

Thoughts?

[huonw]

(I note that CI fails, I won't put energy into fixing it until we've agreed on the direction, though.)

[thejcannon]

I think I'm a soft -1 on this. It feels silly to muck with the URLs just to workaround a bug with 404 pages. Once the bug is fixed, we're still stuck with arguably wonky URLs.

That being said I am willing to play around with different schemes. Maybe there's one that isn't wonky?

I wonder if we could do:

• /docs/<version>/<prose path>
• /reference/<version>

By leveraging two instances of the docs plugin, one for docs and one for reference. (Or some way else). Although I don't think that'll work well with versioning.

[huonw]

When you have time, feel free to play around with more complicated options like that. I'll leave this open as an option for now, in case we decide to go with it or one of the similar alternatives I mentioned.

In terms of working around the bug, I don't know when then bug will be fixed: it may be up to us (the pants community), and it's not going to be me.

In terms of priority of a functional 404 page, my assessment is it is critical for the switch-over (hence putting it into https://github.com/pantsbuild/pantsbuild.org/milestone/1): doing a wholesale website rewrite like this seems like a prime time for people to see the 404 pages, e.g. if we have missed any links for redirection or have made mistakes in URLs.

[thejcannon]

This issue can be closed now, since #84 is merged

[huonw]

(typo in issue reference, was #84)