docs: Reorganize documentation information architecture and navigation

[Dindihub]

Summary

This PR addresses some of the recommendations in Umbrella issue #1955 . It redesigns the Vitess documentation Information architecture to improve discoverability and navigation for new users.

Changes

-Moved Releases to top-nav
-Moved the versions to Releases/mentions of them
-Added an intro to Docs
-Moved Overview, Get started, Concepts, User guides, and references out of versions into the sidebar
-Renamed the Local install to Quick start guide
-Moved the Blog further right
-Rearranged items in the Contributing guide

[Dindihub]

@mattlord, here is the PR. I can't see the Netlify preview yet. Looks like it needs your approval.

[netlify]

✅ Deploy Preview for vitess ready!

Name	Link
🔨 Latest commit	d595793
🔍 Latest deploy log	https://app.netlify.com/projects/vitess/deploys/6a928a3ce6d495000844c486
😎 Deploy Preview	https://deploy-preview-2152--vitess.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[mattlord]

We need to revert the changes to this file as I believe it was for the one you had created

[mattlord]

Correct me if I'm wrong, but I was assuming this should be lossless reorganization and it doesn't seem to be currently.. The visual direction is reasonable, and the site builds, but the PR currently removes routes, duplicates versioned documentation, introduces broken navigation, and exposes new broken links.

Merge blockers

1. Seven existing FAQ URLs are lost.

   These generated successfully on prod but are absent from the PR build:

   • /docs/faq/getting-started/overview/
   • Its six child FAQ pages, including /what-is-vitess/

   The deploy preview sends the old child URL through the catch-all version redirect and ultimately displays a 404. The four old /docs/releases/... URLs are correctly preserved with aliases, but the moved FAQ pages have no equivalent aliases.

   Add explicit aliases or Netlify redirects for the overview and every child. A section-level alias will not preserve descendant URLs automatically.

2. The reorganization creates a second, duplicated documentation tree.

   The PR copies 419 Markdown files byte-for-byte from v24:

   • 7 Overview pages
   • 17 Concepts pages
   • 91 User Guide pages
   • 304 Reference pages

   This creates duplicate search results and duplicate crawlable content, and it will drift. In particular, the [generated-reference workflow](

   website/tools/cobradocs/version.go

   Lines 32 to 34 in 8cfe093

   	func (v version) Dir(root string) string {
   	return filepath.Join(root, "content", "en", "docs", v.DocVersion, "reference", "programs", binaryName)
   	}

   ) only updates content/en/docs/<version>/reference/programs; it will never update the new unversioned copies.

   Given the requirement that this is only a reorganization, I recommend keeping v24 as the single content source and changing the navigation to present its sections at the top level. Do not physically copy the documentation.

3. The forced Netlify rule makes the new User Guide tree unreachable.

   These 301! rules forcibly redirect every new /docs/user-guides/... page to /docs/24.0/user-guides/..., even when the unversioned static page exists.

   On the resulting v24 page, the sidebar has no active or expanded item because version sections are hidden. Thus, clicking the new navigation changes the URL and loses navigation context. Either link the reorganized menu directly to the versioned source tree, or remove the forced redirect and establish explicit canonical/versioning behavior.

4. The new Releases link is broken throughout the Chinese site.

   The navbar uses relLangURL, producing /zh/releases/, but the PR adds only English release content and an English translation key. The live preview’s Chinese navbar shows “Releases,” and the link returns 404.

   Add localized content and translation, or deliberately link Chinese pages to the English /releases/ fallback.

5. Existing versioned pages lose their navigation path.

   v23, v24, and v25 are marked hide_in_sidebar, and [the desktop sidebar filters them out](

   website/layouts/partials/docs/sidebar.html

   Lines 5 to 9 in 8cfe093

   	{{ $entries := slice }}
   	{{ range $docsSections.Sections }}
   	{{ if not .Params.hide_in_sidebar }}
   	{{ $entries = $entries | append . }}
   	{{ end }}

   ). Direct visits and inbound links to /docs/24.0/... therefore show no active or expanded sidebar hierarchy.

   The Releases page does not compensate for this: its version headings are plain text and do not link to /docs/25.0/, /docs/24.0/, or /docs/23.0/. Preserve usable navigation on versioned URLs and add clear documentation-version links to Releases.

6. Moved Markdown contains newly invalid relative paths.

   The internal checker reports 42 broken references in the newly added unversioned trees: 38 missing targets and four missing fragments across 21 files.

   A clear example is [content/en/docs/concepts/vtadmin.md:24](https://github.com/vitessio/website/blob/8cfe093d1aac17a79db00e609cea1cabde5b661a/content/en/docs/concepts/vtadmin.md#L24). Its ../../../21.0/reference/vtadmin/ link worked from the deeper versioned path, but from /docs/concepts/vtadmin/ it resolves to /21.0/reference/vtadmin/, which does not exist.

   Every moved relative link needs auditing. Hugo ref/relref links would be less fragile than directory-depth arithmetic.

UI/UX follow-ups

7. The mobile documentation menu was not reorganized consistently.

   [The mobile template](

   website/layouts/partials/docs/header.html

   Lines 61 to 79 in 8cfe093

   	{{ range $docsSections }}
   	<a class="dropdown-item has-text-weight-bold" href="{{ .RelPermalink }}">
   	{{ .Name }}
   	</a>
   	<hr class="dropdown-divider" />
   	{{ range .Sections }}
   	<a class="dropdown-item has-text-weight-bold" href="{{ .RelPermalink }}">
   	{{ .Name }}
   	</a>
   	{{ range .Pages }}
   	<a class="dropdown-item" href="{{ .RelPermalink }}">
   	{{ .Title }}
   	</a>
   	{{ end }}
   	{{ end }}
   	{{ end }}

   ) ignores hide_in_sidebar, still lists all versions, and then dumps their immediate pages into one dropdown.

   At 390×844, the menu contains 111 links versus 65 on prod and is roughly 3,700px tall. It should use the same filtered information architecture as desktop, preferably with nested collapsible sections.

8. The promoted Releases page needs Markdown/content cleanup.

   • It should link release headings to their corresponding documentation.
   • “The latest and current vitess release” is redundant and should capitalize “Vitess.”
   • It says v20.0.6 is current, but [v20.0.8 exists](https://github.com/vitessio/vitess/releases/tag/v20.0.8).
   • The Get Started introduction repeats “install Vitess locally” awkwardly.

[Dindihub]

Thanks for the detailed review @mattlord
I anticipated there would be issues because I moved a lot of things around to achieve this IA.

Thanks for the suggestions. It clarifies how the navigation works and the intended architecture. I'll work on them one by one.

[Dindihub]

Hi @mattlord . I have worked on merge blocker no. 2 to start.
I removed the duplicated files and restored V24.0 as the source for the introductory files. Let me know if this is what you had envisioned.

[mattlord]

Hi @mattlord . I have worked on merge blocker no. 2 to start. I removed the duplicated files and restored V24.0 as the source for the introductory files. Let me know if this is what you had envisioned.

v25 is what will eventually become the v26 docs when we do the first v25 RC. So the v25 docs should be the basis for anything new. If I'm understanding you correctly.

[Dindihub]

Hi @mattlord . I have worked on merge blocker no. 2 to start. I removed the duplicated files and restored V24.0 as the source for the introductory files. Let me know if this is what you had envisioned.

v25 is what will eventually become the v26 docs when we do the first v25 RC. So the v25 docs should be the basis for anything new. If I'm understanding you correctly.

Got it. I'll make it point to V25.0 instead. Something I would like to understand, do the versioned docs change with each release? I noticed that the three versions had the same docs that's why I initially moved them out of the versions where they are visible.

[Dindihub]

Merge blocker 1:
I have added aliases to Faq/overview and subpages as requested. Please confirm that they are correct.

[Dindihub]

Hi @mattlord, I believe I have addressed 7 of the 8 merge blockers by returning the versioned docs and some page updates as suggested. Please confirm.

Merge blocker 7 may be out of my scope as I don't have much experience with mobile. What would you recommend? Happy to take suggestions.

[mattlord]

1. Blocking: I still agree with the existing versioned-navigation concern. The latest changes restore navigation for v25, but v24 and v23 remain hidden in content/en/docs/24.0/_index.md:10 and content/en/docs/23.0/_index.md:10. I think hidden versions should still appear when they contain the current page, so direct links into stable documentation retain their hierarchy.

2. Blocking: In content/en/docs/25.0/get-started/_index.md:10, the visible documentation promotes the quickstart, but the corresponding title and ordering changes were only applied to v24. The rendered v25 navigation still lists the Operator first and “Local Install” second. I think we should apply the quickstart title and weights to v25 as well, since that is now the primary documentation tree.

3. Blocking: In content/en/releases/_index.md:53, the initial v20 GA release was changed from v20.0.0 on 2024-06-27 to v20.0.6 on 2025-02-12. The patch-release list also skips the existing v20.0.7 release. I think we should restore the original GA entry and add v20.0.7 to the patch list.

4. Non-blocking: I agree that the existing mobile-navigation follow-up remains valid. The latest changes still do not update layouts/partials/docs/header.html, so mobile continues to use the old version-heavy navigation rather than the new desktop IA.

5. Non-blocking: content/en/docs/contributing/contributing-to-ast-parser.md:4 uses weeight rather than weight. Hugo ignores it, and the Parser and AST page renders last instead of at the intended position. I think we should correct the key to weight: 5.

[Dindihub]

1. Blocking: I still agree with the existing versioned-navigation concern. The latest changes restore navigation for v25, but v24 and v23 remain hidden in content/en/docs/24.0/_index.md:10 and content/en/docs/23.0/_index.md:10. I think hidden versions should still appear when they contain the current page, so direct links into stable documentation retain their hierarchy.
2. Blocking: In content/en/docs/25.0/get-started/_index.md:10, the visible documentation promotes the quickstart, but the corresponding title and ordering changes were only applied to v24. The rendered v25 navigation still lists the Operator first and “Local Install” second. I think we should apply the quickstart title and weights to v25 as well, since that is now the primary documentation tree.
3. Blocking: In content/en/releases/_index.md:53, the initial v20 GA release was changed from v20.0.0 on 2024-06-27 to v20.0.6 on 2025-02-12. The patch-release list also skips the existing v20.0.7 release. I think we should restore the original GA entry and add v20.0.7 to the patch list.
4. Non-blocking: I agree that the existing mobile-navigation follow-up remains valid. The latest changes still do not update layouts/partials/docs/header.html, so mobile continues to use the old version-heavy navigation rather than the new desktop IA.
5. Non-blocking: content/en/docs/contributing/contributing-to-ast-parser.md:4 uses weeight rather than weight. Hugo ignores it, and the Parser and AST page renders last instead of at the intended position. I think we should correct the key to weight: 5.

Fairly manageable. I am currently having issues with my laptop. I'll work on this as soon as its fixed.