New Theme For Docs Site

[ShaunaGordon]

The Problem

In an effort to get it updated and easier to use/manage, I've been tinkering with the site's theme, and I think it's time we just start looking at a new theme or theme rewrite, for the following reasons:

1. The current theme has Bootstrap 4 deeply embedded, making it difficult to make changes and super element-happy. For example, adding a dark theme to a plain CSS site is trivial, but to o3de.org, it's a major lift.
2. Bootstrap 4 is essentially end of life, and the current theme uses parts of Bootstrap that are deprecated and removed in v5, breaking the site in non-obvious and difficult-to-fix ways.
3. The path forward from here, no matter what, will be a big lift, making this a good time to consider the return on taking the time to do a new theme.

Normally, I try to avoid advocating for rewrites, knowing they tend to be costly, but we're at the point, I think, where major action of some sort is all but unavoidable (I mean...technically it's avoidable, but would mean keeping with EOL tech, so...).

The Options

A Third-Party, Off-The-Shelf Theme

This is easiest solution to get up and running relatively quickly, and knock out a lot of the pending feature requests for things like dark mode and PDF export. There are a number of good options to choose from that get us a nice, featureful interface. I'm partial to Shadocs, because it's already close to what we already have and explicitly has a lot of our wishlist items, and does it without external dependencies, allowing us to drop the NodeJS dependency. Docsy also ranks up there for similarity, as is Plume.

The biggest drawback to this is that we're largely at the mercy of the theme's maintainers to keep things updated and for their design and tech choices. Overriding theme elements requires creating custom templates that override theme ones. However, we can keep our customizations in the hugo-odie repository and chain module imports (odie imports the upstream theme), continuing to house our customizations, and the main o3de.org repo continues to just import hugo-odie.

Rewrite Hugo-Odie

The other option is to do our own ground-up rewrite. This is a larger task by default and does place the onus on us to keep it updated and provide the necessary features, but gives us full control over the theme, allowing us to really tailor it to our content and branding, and to change the theme itself whenever we need to do so. It also gives us full control over the technological choices, allowing us to add or refrain from dependencies as we see fit.

The Tasks

Regardless of the option we go with, there are a number of tasks we'll need to do to keep the site working properly:

1. Update shortcodes for new HTML structure. The custom shortcodes are tightly coupled with Bootstrap 4, as well, so those will still need updated.
2. Consolidate brand colors for use in new theme.
3. Create light and dark color palates.
4. Update netlify.toml accordingly.
5. Clean up hugo.toml and edit it for the new theme.
6. Ensure tabbed views are still in place.

[ShaunaGordon]

@GaianHelmers @JT-SCB-GameDesign I'd love your thoughts on this in particular.

[GaianHelmers]

I am definitely in a position of wanting to have as little responsibility/demand for resources as possible in realms that have no involvement in the actual progress of the engines development. Sure you can say documentation is directly related to that, but the theming in an otherwise well served market shouldn't need to be on us to upgrade and maintain.

Having used Docsy, I have found the experience to be pretty well the same as I have encountered in the current docs, and thus don't see why we would want to have such granular control of a common web usage format. It's not like we're "re-inventing how you use documentation™"

Plume looks quite pleasing, I feel that search block in the menu looks more professional than Docsy's bubble search box.
Although, plume is definitely pretty stark in light and dark modes. We would likely want to soften those colours.

I definitely also prefer to have the local operation and running of the documentation to be a LOT easier to use. I still haven't been able to get it to run locally, while my implementation of Docsy is one and done.