feat(docs): Overhaul documentation platform with Next.js

[RoseWrightdev]

TLDR

1. Port the existing documentation to Next.js using the AriaDocs template for a fast UI/UX modernization.
2. Implement robust absolute routing, automated redirects, and dynamic internal linking to improve the author experience and SEO, leveraging next.config.js.

Fixing The Foundation

The documentation looks dated, and the navigation is confusing. We’re long overdue for an overhaul, but we’ve been putting it off for years because it’s prohibitively time-consuming due to hardcoded links and serious SEO concerns. We need to fix this before moving forward.

Proposed Solution

We will use an off-the-shelf Next.js template—similar to the Next.js documentation itself—called AriaDocs for a drag-and-drop facelift with a modern suite of features developers have come to expect.

We will build a custom, automated system to handle routing, redirects, and internal linking. This system will be built around a build-time script that ensures all content URLs are permanent, all legacy paths are correctly redirected, and all internal links are unbreakable, all leveraging next.config.js.

1. Absolute Routing

Goal: All content will be served from clean, permanent, and SEO-friendly absolute URLs.

Mechanism: Every MDX file will define its public URL via a frontmatter property.

--

id: 'a2b4c6d8-e1f3-4a5b-9c8d-7e6f5a4b3c2d'

title: 'My Awesome Post'

seoPath: '/guides/my-awesome-post'
--

Content goes here...

The build script will use these seoPath values to generate rewrite rules in next.config.js, mapping the public URL to the underlying Next.js page structure.

Edge Cases: The build script will enforce the following rules:

• Uniqueness: The build will fail if two MDX files declare the same seoPath or id.
• Valid Format: The build will fail script will validate that every seoPath is a valid, lowercase, URL-safe string beginning with /. The build will fail on invalid formats.
• Presence: The build will fail if any MDX file is missing a seoPath or id property.
• No Reuse of Redirected Paths: The build will fail if a new page attempts to use a seoPath that is already recorded as a legacy path in the redirect history.
• Reserved Paths: The script should maintain a list of reserved paths (e.g., /api,/public) and fail the build if a seoPath conflicts with them.

2. 301 Redirect Generation

Goal: Automatically create and manage permanent (301) redirects when a page's seoPath changes, preserving SEO value and preventing broken links from the outside world.

Mechanism: The build script will maintain a historical record of all seoPath values from previous successful builds (seoPath-history.json). Each new build will compare the current seoPaths against the history. If a path has changed, it will automatically generate a 301 redirect from the old path to the new one and add it to next.config.js.

Edge Cases: The redirect generation script must be intelligent enough to handle:

• Redirect Chains: If a URL changes multiple times (A -> B, then B -> C), the script will flatten the chain by creating a direct redirect from all legacy paths to the final destination (A -> C).
• Content Deletion: If an MDX file is deleted, its seoPath will be "orphaned." The build will fail and report these orphans, forcing a developer to make a conscious decision:
  1. Create a manual redirect to a relevant fallback page.
  2. Explicitly mark the content as 410 Gone to inform search engines it has been permanently removed.
• Circular Redirects: The build will analyze all proposed redirects and fail if it detects a loop (A -> B and B -> A).

3. Dynamic and Resilient Internal Linking

Goal: Eliminate fragile, path-based internal links and replace them with unbreakable, ID-based links.

Mechanism: We will introduce a custom React component, <InternalLink>, for all internal linking within MDX. Instead of a path, authors will link to a page's unique, permanent id from its frontmatter.

Example Usage:

To learn more, see our guide on <InternalLink contentId="a2b4c6d8-e1f3-4a5b-9c8d-7e6f5a4b3c2d">Awesome Posts</InternalLink>.

At build time, the <InternalLink> component will use a map of all contentIds to their current seoPaths to resolve the correct href. This ensures that even if a page's URL changes, all internal links pointing to it will update automatically.

Edge Cases:

• Guaranteed Link Integrity: The build must fail if an <InternalLink> component references a contentId that does not exist, eliminating broken internal links from the deployed site.
• Anchor Links: The component will accept an optional hash prop to handle linking to specific sections: <InternalLink contentId="..." hash="#section-heading">Link to a section</InternalLink>
• Linting for Standard <Link> tags: We should add an ESLint rule to flag the use of standard <Link href="..."> tags for internal links, guiding authors to use <Link> instead.

System-Level Considerations

• Bootstrapping: The build script will have a "first run" mode to generate the initial seoPath-history.json file without creating any redirects.
• Redirect History File: The seoPath-history.json file must be committed to the Git repository to ensure the history is version-controlled and consistent across all development and CI/CD environments.
• History File Corruption: The build script should perform basic validation on seoPath-history.json at startup to detect and report obvious corruption.
• Manual Overrides: The system should allow for a separate, manually curated list of redirects that takes precedence over the generated ones. This provides an escape hatch for complex or exceptional cases.
  • The build script should log a warning whenever a manual redirect rule overlaps with a page's current seoPath or a generated redirect.
• Developer Experience: The behavior of next.config.js (requiring a server restart to see changes) should be documented for contributors. We may investigate a file watcher like chokidar to prompt for a restart on seoPath changes if this becomes cumbersome.

Acceptance Criteria

• All documentation content is successfully migrated to MDX in a new Next.js application.
• The build process includes a script that implements all specified routing, redirect, and linking features and their associated edge case.
• Internal documentation is updated to instruct authors on using the new id, seoPath, and <InternalLink> features.
• The live site has no broken internal links and correctly redirects all renamed legacy URLs.

Next Steps

Long-term, we need to start thinking about content strategy and best practices to implement going forward from resources like: 1. Diataxis (Used by Github) 2. Google’s Documentation Style Guide 3. Doc For Developers by Jared Bhatti, Sarah Corleissen, Jen Lambourne, David Nuñez, Heidi Waterhouse. (This is a paid resource, but I'll finish reading it in a few weeks and summarize.)

[candita]

Thanks, this will be great. One suggestion: https://kubernetes.io/docs/contribute/style/style-guide/ is a preferred resource for style.

[RoseWrightdev]

~We're currently using MKDocs, and it lacks the functionality we need because it's just a simple static site generator. As it stands in the proposal, the next.config.js networking APIs do most of the work for us. Whatever framework we choose, we need a similar set of APIs to do this work because rewriting this functionality from scratch would massively expand the project. Right now, we are essentially just piping JSON data to the API; without it, this project becomes entirely impractical. We also need MDX and React at a minimum to implement something like the <InternalLink/> component. Another point is the wealth of templates and off-the-shelf components available in the Next.js/React ecosystem, like shadcn. I don't want to reinvent the wheel.~

Edit: I was gravely underestimating mkdocs! As @blake pointed out, much of this is possible within mkdocs without porting to Next.js. We could also polish these existing features with a Python hook or, as Blake said, a Git pre-commit hook.

[shaneutt]

I appreciate this well thought out proposal for an overhaul, our website is notoriously difficult to navigate. We discussed this on the call today, and there were some questions such as whether we can achieve any of the goals while sticking with the mkdocs, and how to maintain this sort of thing in the long run.

Do you have an example repository containing a site that uses this same tech stack? Ideally something small and illustrative?

[RoseWrightdev]

I appreciate this well thought out proposal for an overhaul, our website is notoriously difficult to navigate. We discussed this on the call today, and there were some questions such as whether we can achieve any of the goals while sticking with the mkdocs, and how to maintain this sort of thing in the long run.

Do you have an example repository containing a site that uses this same tech stack? Ideally something small and illustrative?

Tech stack as in Next.js with the Aria docs template? I'm not sure what you mean.

[snorwin]

In my view, the current content structure feels disorganized and fragmented, which makes navigation quite difficult. That said, I’m less concerned about whether links are hardcoded or whether the site is optimized for SEO.

What matters most to me is that this is technical documentation authored by developers and engineers. Because of that, I believe we should continue using a simple format like Markdown or AsciiDoc as the content source. The Gateway API site isn’t intended to be a flashy marketing website, and it should prioritize clarity, accuracy, and ease of contribution from technical folks.

If there are technical limitations or issues with the current MkDocs setup, I think it would be more valuable to raise them within the MkDocs project itself. Rather than switching frameworks, I’d prefer to invest our effort in restructuring and rewriting the actual content to improve its quality and usability.

[blake]

It feels like the primary motivation of this proposal is to avoid broken URLs. If that's the case, I think there's an opportunity to solve for most of these issues with the current docs system.

1. Absolute routing

MkDocs already avoids some of the identified edge cases by building URLs based off of the underlying directory structure. (MkDocs: Writing your Docs - File layout). It's not possible for pages or assets to have the same URL because two distinct resources cannot exist at the same file path.

Reserved Paths: The script should maintain a list of reserved paths (e.g., /api,/public) and fail the build if a seoPath conflicts with them.

I think this can already be accomplished by using the exclude_docs configuration parameter. This won't cause the build to fail, but it should achieve the intended result by excluding any content that may be introduced under these reserved paths.

# This prevents in the following directories under site-src/ from being included when the site is built.
exclude_docs: |
  /api-types/
  /geps/

2. 301 Redirect Generation

Renaming URLs is currently a bit of a pain because doing it correctly involves a few steps as you identified.

1. Move the file to a new location
2. Add a redirect under the redirects map in mkdocs.yml
3. Optionally update all files that reference the new file location. (This could be automated with a Git pre-commit hook.)

3. Dynamic and Resilient Internal Linking … Guaranteed Link Integrity: The build must fail if an <InternalLink> component references a contentId that does not exist, eliminating broken internal links from the deployed site.

It's possible to enable this in MkDocs by setting a number of validation rules to warn and enabling the strict build mode.

[Seo-yul]

I used MkDocs to work on the localization https://github.com/kubernetes-sigs/gateway-api/issues/3882 Through this issue, I was able to understand how the MkDocs structure can cause certain path-related issues. (I think this is the topic now,)

However, I fully agree with @snorwin 's opinion. Although I am a Go engineer, I had no problem contributing using MkDocs. (Since I’m not a Next.js user, my perspective might have been off focus.)

While I believe that documentation maintenance is the responsibility of contributors and is definitely manageable, this experience also made me realize how beneficial it would be if technical maintenance could be supported.

[candita]

@RoseWrightdev here's a list of concrete suggestions. It may not align with Diataxis, but I think that model represents an ideal that doesn't fit all situations. For example, it doesn't tell you how to approach a case where you have very different audiences, e.g. we have both users and implementers sharing these docs so that guides and tutorials are going to converge in some cases.

In the Documentation Outline, consider putting the Explanations first in the menu, I suggest it be called “Concepts”. We are missing a few use cases from the Use Cases.

Under Best Practices - Versioning Strategy should probably go in Core Concepts, with API Development Methodology, if it points to https://gateway-api.sigs.k8s.io/concepts/versioning/

We don’t have tutorials yet, but we can provide some examples from various documentation sets (I have some, and implementers like Envoy Gateway do too, etc.). Talks and presentations probably belong under the tutorials section to some extent.

How-to Guides are missing a few of the guides in https://gateway-api.sigs.k8s.io/guides/ - cross-namespace routing, backend protocol selection, infrastructure attributes.

The “Ecosystem & Tooling” category seems misnamed - we want these links for both implementors and end users. Maybe a better name would be “Implementations and Conformance”.

We’re missing a FAQ.

The list of GEPs, which contain material about the state of a feature request, should not be under Contributing. Imo it deserves its own section, as it currently has. Also, we have a few other categories than Standard, Experimental, and Provisional.

Upgrade Guides would belong under How-to Guides, not API Reference, if we had any. It is really something that should be covered by each implementation’s documentation, not the API documentation so it may be safely omitted.

In the Phase 2 of the rollout plan when each page is audited, if it needs changes, you could just add a banner: “under construction”, or something similar. After we find out how many changes are needed, we could then prioritize them, or delete them, or combine content as needed.

[RoseWrightdev]

@candita I think all of these suggestions are great! I plan to implement all of them. Thanks for the feedback.

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue as fresh with /remove-lifecycle stale
• Close this issue with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[rikatz]

;lifecycle active

[rikatz]

/lifecycle active