Simplify flavor+version navigation paths

[aneta-petrova]

What changes are you introducing?

I'm trying to simplify the way users can navigate docs.theforeman.org, namely by:

• Removing the current flavor dropdowns from the top menu bar and replacing them with new version pages, each with collapsible lists
• Removing a few links from the main landing page and adding them to the top menu bar instead

I'm trying to make use of native AsciiDoc features as much as possible (hence the use of collapsibles) so that it's easy to understand and modify by writers.

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

I'm trying to address these issues that currently affect docs.theforeman.org:

• Users can't use full-text search to find the guide they need
• Navigating between the flavors and versions is not straightforward enough

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

That's a lot of changes in a single PR. Based on how the reviews go, I can break it into smaller ones.

Checklists

• I am okay with my commits getting squashed when you merge this PR.
• I am familiar with the contributing guidelines.

Please cherry-pick my commits into:

• Foreman 3.13/Katello 4.15 (EL9 only)
• Foreman 3.12/Katello 4.14 (Satellite 6.16)
• Foreman 3.11/Katello 4.13 (orcharhino 6.11 on EL8 only; orcharhino 7.0 on EL8+EL9)
• Foreman 3.10/Katello 4.12
• Foreman 3.9/Katello 4.11 (Satellite 6.15; orcharhino 6.8/6.9/6.10)
• Foreman 3.8/Katello 4.10
• Foreman 3.7/Katello 4.9 (Satellite 6.14)
• We do not accept PRs for Foreman older than 3.7.

[github-actions]

The PR preview for 594df50 is available at theforeman-foreman-documentation-preview-pr-3657.surge.sh

The following output files are affected by this PR:

show diff

show diff as HTML

[aneta-petrova]

Notes from today's triage: Generally, ack, this is seen as an improvement over the current website navigation.

Current blocker: Not all version files (the ones linked from the version dropdown) are currently populated with a list of guides. I will add this.

Also, I want to experiment with different options for how to present the collapsible lists, to find out if it's possible to keep the Katello list uncollapsed by default.

[ekohl]

In general I agree with the drop down menus being gone because they're getting too long and don't scale.

In #1204 I played around with having those landing pages within the branches themselves. It may be worth investigating that again. I think long term it can easy maintenance.

[aneta-petrova]

In #1204 I played around with having those landing pages within the branches themselves. It may be worth investigating that again. I think long term it can easy maintenance.

That is what worries me most about the solution I propose: That maintaining a list of guide links manually for each version is heavy maintenance. But then again, I try to keep in mind that we also need a solution that is easy to understand and update by any writer.

[ekohl]

My idea comes to have something like guides/index.adoc in every branch and then somehow gather all of those when building the website. That way the index lives very close to the actual guides. For me it's hard to estimate if that would be easy to understand by any writer, but I think it would because (as you also said) it's using tooling writers are already familiar and in a directory you already work in.

To be clear: I don't mean we need to block your effort on it and it can be done as a follow up.

[aneta-petrova]

Also, I want to experiment with different options for how to present the collapsible lists, to find out if it's possible to keep the Katello list uncollapsed by default.

@maximiliankolb To follow up on this, these are two things I tried:

I have to say that I still prefer the current, collapsed by default. To me, it still seems like the simplest and cleanest solution, and I don't think the one extra click is too much of an issue:

I'm going to proceed with the collapsed-by-default approach and, as discussed at today's triage, we can always improve later :)

[ekohl]

Something I thought about was taking more of the tabs approach, but no idea if it's actually feasible/usable.

Basically have a header that's Foreman $version and then 3 big tabs:

• Foreman on EL
• Foreman on Debian/Ubuntu
• Katello

Depending on the tab, you see the list of guides. You can also consider adding logos to the tabs for additional visibility. The asciidoc tab plugin can use cookies to store the user's preference so if you navigate to other versions it should remember what the user has.

[aneta-petrova]

I couldn't get tabs to work: I tried on my own and then also when I checked out your web branch. I never got the tabs, always just the example block. That's when I thought of collapsible lists as an acceptable alternative.