Replace links in custom footer by MkDocs navigation

[wenzeslaus]

Replace the custom footer links to index pages by MkDocs nav (menu) items. This can be at the top or the bottom and it does not have to the exact links or wording, the point is to have whatever is the best, not necessarily the original.

The current footer has an issue that the links either don't work for addons which are in a subdir or they need to be absolute URLs, so they would link to a wrong version and always online. This is due to an MkDocs limitation ("it's not possible to use relative links at this point"). Rather than overcoming the issue, our time is probably better spent on creating a better navigation rather than maintaining a block of links which were replacing a missing navigation in the custom HTML doc.

This may actually remove the need to have the large partial footer file which does not seem to be something we want to maintain - there is a ton of general code which we don't customize and the only reason we customize it are the footer links:

<center>
        <a href="{{ config.site_url }}index.html">Main index</a> | <a href="{{ config.site_url }}topics.html">Topics index</a> | <a href="{{ config.site_url }}keywords.html">Keywords index</a> | <a href="{{ config.site_url }}tags.html">Tags index</a> | <a href="{{ config.site_url }}graphical_index.html">Graphical index</a> | <a href="{{ config.site_url }}full_index.html">Full index</a><br>
</center>

Current state

[wenzeslaus]

My current take on this:

• Main index: Already available at the top by clicking at the logo. Will be also available from the horizontal (top) menu after docs: MkDocs index and nav redesign #5207.
• Topics index: Suggestions welcome on what to do with topics in general. A variation of this page can also be generated by picking a list of tags for tags listing (like tag index but with selected tags only; unlike the current index, it would show the links to tools, but without descriptions unlike the individual topic pages).
• Keywords index: Linked from every page using the individual keywords. Possibly merge with tags.
• Tags index: Linked from every page using the individual tags. Possibly merge with keywords.
• Graphical index: Experimental, inherited from the custom HTML doc. No need to have it here.
• Full index: Will be available from the horizontal (top) menu after docs: MkDocs index and nav redesign #5207 as index for all tools which is what it is (full index of tools).

[wenzeslaus]

Any opinions on dropping the bottom menu?

You can get the full documentation for yourself by downloading an asset generated from the Documentation workflow in Actions tab or browsing commits on main. The artifacts expire but a latest one currently is: https://github.com/OSGeo/grass/actions/runs/13842127864/artifacts/2747987237

[veroandreo]

Any opinions on dropping the bottom menu?

You can get the full documentation for yourself by downloading an asset generated from the Documentation workflow in Actions tab or browsing commits on main. The artifacts expire but a latest one currently is: https://github.com/OSGeo/grass/actions/runs/13842127864/artifacts/2747987237

I would drop it, it doesn't really fit with the new layout and it links to pages with old layout so the contrast is impressive

Does dropping this bottom menu mean we also drop the topic and keyword listing? Maybe this was discussed elsewhere, I just was not able to keep up with the huge amount of issues and PRs on docs (which is amazing! 💯 not complaining!)

[BobRuediger]

If you are already planning to house the Full Index elsewhere, I would drop the footer altogether and keep all of the indexes together with the Full Index (or perhaps as subsections of the Full Index if the hierarchy permits). It sounds like the development issues caused by the current state are not worth the benefit they provide to users by being ever-present.

[Just my opinion as I'm slowly jumping in here.]

[wenzeslaus]

I would drop it, it doesn't really fit with the new layout...

I agree. I also think that the navigation is done in a different way now.

and it links to pages with old layout so the contrast is impressive

Indeed it is, but going online to the old layout is an unrelated issue. When the new doc would be online for stable version, it would go to the new layouts. However, the fact that it links to online version is a bug introduced while countering another bug which speaks to the complexity this introduces (complexity in the sense that this is thing which MkDocs is not build to handle at this point).

Does dropping this bottom menu mean we also drop the topic and keyword listing? Maybe this was discussed elsewhere, ...

There is no other discussion besides the bullet points above. We can use tags instead of keywords while still calling them keywords and keep the the URLs. We can also keep generating topic pages. There is probably no need to list keywords for each tool again and just link to topic in one case like the custom listing does. This is worth another issue.

...I just was not able to keep up with the huge amount of issues and PRs on docs (which is amazing! 💯 not complaining!)

Good! :-) We trying to have issues in addition to PRs and we have a project, checklists, sub issues, all that trying to facilitate reviews or diving into it in general. However, it is a lot and we discovered many things only along the way. It is a lot of work, much more than expected, and without the tracking, I would have hard time figuring out the status myself.

[wenzeslaus]

If you are already planning to house the Full Index elsewhere, I would drop the footer altogether...

The full_index.html is what you get now with Processing Tools, so yes, it is already linked from elsewhere.

...and keep all of the indexes together with the Full Index (or perhaps as subsections of the Full Index if the hierarchy permits).

The full index here is a list of all tools. So the naming is little misleading, it is not index of all pages, only of all tool pages.

It sounds like the development issues caused by the current state are not worth the benefit they provide to users by being ever-present.

And we actually get the always-present link with the top menu for the full index page.

[Just my opinion as I'm slowly jumping in here.]

Thanks!

[wenzeslaus]

See PR #5427 which removes the footer.