Migrate theme from Docsy to Hextra for modern documentation UX

[jkhelil]

Summary

• Theme migration: Replace the stock Docsy theme (v0.6.0, circa 2018) with Hextra v0.12.0 — collapsible sidebar, sticky TOC, Ctrl+K search, dark mode toggle, responsive design.
• Landing page redesign: Hero section with CNCF incubating badge, "Why Tekton?" value-prop cards, "Trusted By" adopters strip, workflow diagram, and quick-access Get Started cards.
• Getting Started overhaul: Guided card layout (Pipelines first, PaC second with full content), step-by-step flow.
• Installation restructure: Local cluster → Pipelines → Triggers → Operator (new) → Additional Config.
• Community page rework: Card-based layout with color-coded sections and dark mode support.
• Branding: Tekton horizontal color logo in navbar, dark mode toggle in header.
• Sync script fix: sync.py now outputs standard YAML front matter (no <!-- --> wrappers) so Hextra parses weights/titles correctly. All 23 tests pass.

Test plan

• Verify Netlify deploy preview renders correctly
• Check sidebar collapses and orders correctly across all doc sections
• Confirm dark mode toggle works in header
• Verify landing page on desktop and mobile
• Confirm community page cards render properly
• Test Ctrl+K search
• Verify make sync produces valid front matter
• Check Getting Started order: Pipelines → PaC → Triggers → Supply Chain
• Check Installation order: Local cluster → Pipelines → Triggers → Operator → Additional Config

Made with Cursor

[tekton-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
To complete the pull request process, please assign twogiants after the PR has been reviewed.
You can assign the PR to them by writing /assign @twogiants in a comment when ready.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[jkhelil]

@vdemeester @AlanGreene
The Hugo build completes successfully (592 pages), but the Netlify deploy preview fails in the post-build step because of the netlify-plugin-checklinks plugin.

plugins:
    - inputs: {}
      origin: ui      ← installed via dashboard, not your code
      package: netlify-plugin-checklinks

The problem: Hextra uses hx: as a CSS class prefix (from Tailwind). The checklinks plugin parses the generated HTML as strict XML and misinterprets hx: class names as XML namespace declarations, producing thousands of false-positive "duplicate attribute: xmlns:hx" errors. This is a known incompatibility — the plugin's HTML/SVG parser simply doesn't support Hextra's output format.

I've already commented out the plugin config in netlify.toml, but the plugin is also installed at the UI level (origin: ui in the build logs), so it still runs regardless of what's in the config file.

Ask: Could youremove (or disable) netlify-plugin-checklinks from the Netlify site settings?

Impact assessment:

The plugin only performs post-build link validation — it does not affect the site build or deployment in any way. Removing it means link checking stops running, but the site continues to build and deploy identically.
The current production site (Docsy on main) will keep working exactly as it does today, just without the automated link check.

Let me know if you have any questions or concerns.

Thanks!

[AlanGreene]

Plugin disabled, the build is now successful, and the preview is available 👍

[AlanGreene]

Just spotted some odd behaviour on the preview:

I see the latest commit updated the default theme to light from the previous value of system. Was support for the system option removed? I don't see it anymore once I select one of the others, but I believe it would be better to have that as the default.

[jkhelil]

Just spotted some odd behaviour on the preview:

I see the latest commit updated the default theme to light from the previous value of system. Was support for the system option removed? I don't see it anymore once I select one of the others, but I believe it would be better to have that as the default.

yeah have seen few website removing the system theme, i agree, we have to keep it as defautl, bring it back

[waveywaves]

Can we add a way for the user to "join the Tekton slack"

[waveywaves]

can we have the component releases dynamically update the website as well ?

[tekton-robot]

@jkhelil: PR needs rebase.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[afrittoli]

/hold

For me this PR, as it is now, is a no-go.
It's a template provider, style and content change all at once.

There's no way I can review this change all at once and get any level of confidence that the website is the same as before.
Is the link structure being preserved? I would not want to break all links an search results out there.

Also I would like to understand what Hextra provides that we didn't get with Docsy, since the change requires a significant change in the website code.