Discussion: Website revamp — feedback on proposed refresh & technical evaluation of tooling (Hugo+Docsy and Docusaurus)

Summary

This issue tracks a broader website revamp effort for tekton.dev:

1. Gathering feedback on the proposed refresh.
2. Running a technical evaluation of our tooling — keeping Hugo + Docsy and also exploring Docusaurus side by side. No decision is being proposed here; the goal is to understand which fits our needs better technically (versioning, i18n, content sync, search, maintenance), independent of how popular either tool is.

There is currently no dedicated issue/discussion for this — only incremental items (#709 Hugo bump, #191 search, #521 docsy submodule). Let's use this as the umbrella discussion.

Proposed refresh

Live preview: https://pankajshivpuje.github.io/tekton-website-refresh/

Note: the proposed refresh is still built with Hugo (generator content="Hugo 0.147.0") using a custom theme rather than Docsy — i.e. primarily a theme/UX refresh, not a generator migration.

Feedback wanted on:

• Navigation / information architecture (Documentation, Components, Solutions, Case Studies, Blog, Community)
• Search experience
• Light/Dark/System theming
• Landing page and component pages
• Mobile responsiveness
• Anything missing vs. the current site

Tooling: technical evaluation (Hugo+Docsy vs Docusaurus)

The current site uses Hugo + Docsy. We want to explore Docusaurus as well — not because of its adoption elsewhere, but to assess whether it technically fits our needs better. No decision yet.

Things to evaluate concretely against our requirements:

• Multi-version docs — Tekton ships many components, each with multiple released versions. How well does each tool handle versioned documentation sets and version switching? (Docusaurus has first-class versioning; how does it compare to our current Hugo setup?)
• Content sync from component repos — our docs are aggregated from multiple tektoncd/* repos via sync/. How would each tool fit that pipeline?
• i18n / localization support.
• Search (see #191).
• Build performance at our content size.
• Authoring — Markdown vs MDX/React components; impact on contributors.
• Maintenance & contributor skill set — Go/Hugo vs Node/React.
• Migration cost if we ever moved (content, layouts, shortcodes, redirects).

For context, an informal survey of CNCF docs tooling (verified from repos) — for reference only, not a decision input:

Suggested next step

Build a small proof-of-concept with Docusaurus covering a representative slice (one component, 2-3 versions, the sync flow) and compare it against our current Hugo+Docsy setup on the criteria above. Results feed back into this discussion.

Asks

• Maintainers & community: please review the proposed refresh and leave feedback here.
• Input on the technical evaluation criteria above — anything missing?
• Volunteers interested in helping with a Docusaurus PoC.

Start by reviewing the current Hugo + Docsy setup and the sync/ entry point, then compare the proposed Docusaurus proof of concept against a representative component with 2–3 versions. Evaluate versioning, content sync, i18n, search, build performance, authoring, maintenance, and migration cost. Done means documented comparison results that address the listed criteria and feed back into this discussion.