search

helm / helm-www

The Helm website for docs, blog and project info.
https://helm.sh
MIT License
203 stars 513 forks source link

Consider using Docsy theme or alike for Hugo, to make navigation in site much easier #1002

Open davidpelfree opened 3 years ago

davidpelfree commented 3 years ago

Hi.

It's very difficult to me to keep orientation while browsing Helm Docs site. There is no full detailed TOC on the left sidebar (using Chrome, on Firefox it works), nor "in page anchor index" at the right sidebar.

Looking at Kubernetes site, it's much easier to navigate the site and know exactly where you are in the documentation: left sidebar with detailed TOC and right sidebar with in-page section navigation.

I found that both Kubernetes and Helm documentation sites use Hugo. So the difference is only in the selected theme.

Therefore I suggest moving to "Docsy", which is used by Kubernetes, or use something similar.

Here's an example showing how easier it to navigate using Docsy theme: https://example.docsy.dev/docs/tasks/ponycopters/launching-ponycopters/#header-3

Thanks.

bridgetkromhout commented 3 years ago

Thanks for the feedback! We'll take a look.

flynnduism commented 3 years ago

Docsy is solid theme for building out Hugo documentation sites. I've used it on some recent projects (source) and it works well specifically for docs.

The Helm site is essentially three different sites in one - landing page (intro/marketing) blog page for comms and then the documentation section (which is the bulk of the helm.sh content). Docsy can be adapted to work in this way too - it has blog support, and you can build custom templates for the landing page to maintain the homepage and other custom things that helm.sh has. Changing the theme will always involve a fair amount of work on top of Docsy to get the custom layouts, styling and ultimately recreate the current structure...

I think a cleaner solution would be to bring in the functionality you seek - to add a right-hand-side Table of Contents column (template here) to the Docs template, rather than changing out the whole thing.