HIP-0024: Evaluate static site generators and migrate the docs

[paigecalvert]

Description

Issue to track implementing "Evaluate static site generators and migrate the docs" from HIP: https://github.com/helm/community/blob/main/hips/hip-0024.md

Evaluate, select, and migrate the Helm docs to a modern, open-source static site generator that would improve ease-of-contribution and site functionality.

Tasks

• (In progress) Evaluate and select SSG (Target completion date: Team selects SSG by June 27):

  • [x] Use Helm Docs Static Site Generator Evaluation to complete eval for:

    • [x] Docusaurus. See Docusaurus Eval notes
    • [x] Hugo + Docsy. See Hugo + Docsy Eval notes
    • [x] MkDocs. See MKDocs Eval notes
    • [x] VitePress. See VitePress Eval notes
    • [x] Astro + Starlight. See Astro + Starlight eval notes

  • [x] Fill out "Summary of findings" in Helm Docs Static Site Generator Evaluation with results of evals to share with the team.

  • [ ] Propose which SSG to use based on the results and get alignment from the team.

• Migrate Helm docs to new SSG:

  • [ ] In a branch, create a sample preview of the Helm docs with the new SSG. Preview must include:
    • [ ] Placeholder text (lorem ipsum)
    • [ ] Must have CSS (fonts, colors, background image, logo/favicon).
    • [ ] Version dropdown
    • [ ] Translations dropdown
    • [ ] Configure landing page, footer, and top navbar
  • [ ] Host the preview on GitHub pages for sharing
  • [ ] Address feedback from team, as needed
  • [ ] Migrate the v2 and v3 Helm docs (as necessary, use git mv to maintain commit history).
  • [ ] Migrate the translated versions of the v2 and v3 docs
  • [ ] Test the migration:
    • [ ] Versioning dropdown works as expected
    • [ ] Translations dropdown works as expected
    • [ ] No broken links or anchor links
    • [ ] Local build runs without error
  • [ ] Update the readme for helm-www with information about the new SSG and build process. Include instructions for how to run a local preview.
  • [ ] Merge the migration PR after team is aligned.
  • [ ] Announce the update to relevant channels (helm-dev channel, cncf tech docs channel, etc)

[paigecalvert]

Monday 06/23/25: Updated the Helm Docs SSG Evaluation doc with my eval notes and recommendations. Shared with the Helm dev team here: https://kubernetes.slack.com/archives/C51E88VDG/p1750697074043249

The TLDR is that I'd lean towards one of the following options:

• Astro with Starlight integration: This one wasn't in our original list of SSGs, but I gave it a shot after Patrice from the CNCF tech docs team recommended it. Overall great; the only downsides were related to somewhat limited customization around the versioning functionality.
• Hugo with Docsy theme: This would be the ol' reliable option that has been the recommended SSG for CNCF projects for some time. It meets the Helm docs requirements and has the added benefit of lots of expertise/experience on the CNCF tech docs team. I didn't find it to be the easiest to work with of the bunch and I don't think it has the most modern look-and-feel, but it checks all the boxes (after some customization).

[TerryHowe]

I don't have a vote here, but if I did, I'd vote for Hugo/Docsy.

From what you are evaluating, I've used Hugo, MkDocs and Docusaurus.

[scottrigby]

Now that we have our first helm 4 pre-release out, I think we should hop on this.

Hugo would be fine.

My vote however would be for Docusauraus, since it solves some of the documentation problems really well, version handling experience for end users is really nice - and not hard for us to maintain. The only potential downside of Docusaurous Paige found online was possible performance issues at build time, which - in my opinion - are not an issue for us. We don't build that often, and we have finite content. The end user experience is fast and modern.

[paigecalvert]

Closed by #1850