Skip to content

release-8.5: implement a new information architecture for TiDB and TiDB Cloud docs#21336

Merged
qiancai merged 32 commits intorelease-8.5from
feature/preview-top-navigation
Feb 11, 2026
Merged

release-8.5: implement a new information architecture for TiDB and TiDB Cloud docs#21336
qiancai merged 32 commits intorelease-8.5from
feature/preview-top-navigation

Conversation

@qiancai
Copy link
Collaborator

@qiancai qiancai commented Feb 9, 2026

What is changed, added or deleted? (Required)

This PR reorganizes the documentation structure and improves experiences of developers by making the following changes:

  • Introduces new top-level navigation categories for AI, API, Best Practices, Developer Guides, and TiDB Releases, providing a clearer and more intuitive information architecture.
  • Adds dedicated Table of Contents (TOC) files for these categories to streamline navigation and improve content discoverability.
  • Reorganizes AI documentation by consolidating all AI-related content into a new top-level ai/ directory (migrated from vector-search/), adding a new landing page (ai/_index.md), and updating internal links accordingly.
  • Restructures the Developer Guide with a new overview page (develop/_index.md), clearer sections for TiDB basics, language and ORM integrations, and MySQL client tools, while aligning existing documents with the new structure.
  • Centralizes API documentation under a new api/ directory, including dedicated overview pages for TiDB Cloud APIs (v1beta1 and v1beta) and TiDB Self-Managed APIs (TiProxy, Data Migration, Monitoring, TiCDC, and TiDB Operator).
  • Cleans up and simplifies documentation content by removing platform-specific CustomContent tags across multiple sections, creating a more unified and maintainable documentation base.
  • Updates numerous internal links throughout the documentation to reflect the new structure and ensure consistency.

Which TiDB version(s) do your changes apply to? (Required)

Tips for choosing the affected version(s):

By default, CHOOSE MASTER ONLY so your changes will be applied to the next TiDB major or minor releases. If your PR involves a product feature behavior change or a compatibility change, CHOOSE THE AFFECTED RELEASE BRANCH(ES) AND MASTER.

For details, see tips for choosing the affected versions (in Chinese).

  • master (the latest development version)
  • v9.0 (TiDB 9.0 versions)
  • v8.5 (TiDB 8.5 versions)
  • v8.1 (TiDB 8.1 versions)
  • v7.5 (TiDB 7.5 versions)
  • v7.1 (TiDB 7.1 versions)
  • v6.5 (TiDB 6.5 versions)
  • v6.1 (TiDB 6.1 versions)
  • v5.4 (TiDB 5.4 versions)

What is the related PR or file link(s)?

Do your changes match any of the following descriptions?

  • Delete files
  • Change aliases
  • Need modification after applied to another branch
  • Might cause conflicts after applied to another branch

lilin90 and others added 18 commits January 15, 2026 07:56
* new nav: create a TOC file for self-managed

* Update TOC.md

* Refactor TOC: split and update documentation structure

Renamed TOC-tidb.md to TOC-pingkai.md and expanded its content with new sections for application development, best practices, and version history. The main TOC.md was simplified by removing these detailed sections, centralizing advanced and historical content in TOC-pingkai.md for better maintainability and clarity.

* Apply suggestions from code review

---------

Co-authored-by: Grace Cai <qqzczy@126.com>
Co-authored-by: Aolin <aolinz@outlook.com>
* *: enrich best practices index and move one doc

* Update _index.md

* Apply suggestions from code review

Co-authored-by: Grace Cai <qqzczy@126.com>

---------

Co-authored-by: Grace Cai <qqzczy@126.com>
* develop: refine wording of two guides

* Update dev-guide-aws-appflow-integration.md
* fix link issues for files

* fix a broken anchor

* Discard changes to scripts/verify-duplicated-file-name.sh

* Discard changes to scripts/verify-links.sh

* Discard changes to scripts/verify-link-anchors.sh

* Delete package-lock.json

* Discard changes to scripts/verify-duplicated-file-name.sh

* Discard changes to scripts/verify-link-anchors.sh

* Discard changes to scripts/verify-links.sh

* revert unnecessary changes
…1304)

* add alias for docs in /develop and /best-practices

* add aliases for vector-search-overview
* sync en changes

* sync EN changes to ZH

* Update dev-guide-create-secondary-indexes.md

* AskTUG —> AskTUG 论坛

* Update develop/dev-guide-connection-parameters.md
@ti-chi-bot ti-chi-bot bot added area/develop This PR relates to the area of TiDB App development. missing-translation-status This PR does not have translation status info. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. labels Feb 9, 2026
@qiancai qiancai added translation/done This PR has been translated from English into Chinese and updated to pingcap/docs-cn in a PR. type/refactor The issue belongs to a refactor work. and removed missing-translation-status This PR does not have translation status info. labels Feb 9, 2026
qiancai and others added 6 commits February 9, 2026 14:36
* chore(package): update package.json and package-lock.json to add new devDependencies for linting and markdown checks

* chore(scripts): adapt package.json

* chore(scripts): add script to verify internal links in TOC files and ensure all referenced pages exist

* chore(ci): restructure CI workflow to add jobs for verifying duplicated file names, internal links, and TOC membership

* chore(scripts): add utils

* chore(scripts): format code for improved readability in internal link verification script
@qiancai
Copy link
Collaborator Author

qiancai commented Feb 11, 2026

/retest

@qiancai qiancai added translation/from-docs This PR is translated from a PR in pingcap/docs. and removed translation/done This PR has been translated from English into Chinese and updated to pingcap/docs-cn in a PR. labels Feb 11, 2026
Copy link
Member

@lilin90 lilin90 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/lgtm

@ti-chi-bot ti-chi-bot bot added the needs-1-more-lgtm Indicates a PR needs 1 more LGTM. label Feb 11, 2026
@ti-chi-bot
Copy link

ti-chi-bot bot commented Feb 11, 2026

[LGTM Timeline notifier]

Timeline:

  • 2026-02-11 06:51:44.385578084 +0000 UTC m=+1257.465568779: ☑️ agreed by lilin90.

@qiancai
Copy link
Collaborator Author

qiancai commented Feb 11, 2026

/approve

@qiancai qiancai added the lgtm label Feb 11, 2026
@ti-chi-bot
Copy link

ti-chi-bot bot commented Feb 11, 2026

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: qiancai

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

The pull request process is described here

Details Needs approval from an approver in each of these files:

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

@ti-chi-bot ti-chi-bot bot added the approved label Feb 11, 2026
@qiancai qiancai self-assigned this Feb 11, 2026
@qiancai qiancai merged commit deaae59 into release-8.5 Feb 11, 2026
9 of 10 checks passed
@qiancai qiancai added needs-cherry-pick-master Should cherry pick this PR to master branch. and removed needs-cherry-pick-master Should cherry pick this PR to master branch. labels Feb 11, 2026
@qiancai
Copy link
Collaborator Author

qiancai commented Feb 11, 2026

/cherry-pick master

@qiancai qiancai added needs-cherry-pick-master Should cherry pick this PR to master branch. and removed needs-cherry-pick-master Should cherry pick this PR to master branch. labels Feb 11, 2026
@qiancai
Copy link
Collaborator Author

qiancai commented Feb 11, 2026

/cherry-pick master

@qiancai
Copy link
Collaborator Author

qiancai commented Feb 11, 2026

/needs-cherry-pick-master

qiancai added a commit to qiancai/docs-cn that referenced this pull request Feb 11, 2026
…DB Cloud docs (pingcap#21336)

Co-authored-by: Grace Cai <qqzczy@126.com>
Co-authored-by: Aolin <aolinz@outlook.com>
Co-authored-by: Lilian Lee <lilin@pingcap.com>
Co-authored-by: Aolin <aolin.zhang@pingcap.com>
Co-authored-by: Yuiham <Yuiham@users.noreply.github.com>
fix broken links in TOC and docs (pingcap#21329)
fix https://do.pingcap.net/jenkins/blue/organizations/jenkins/pingcap%2Fdocs-cn%2Fpull_verify/detail/pull_verify/13964/pipeline
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

approved area/develop This PR relates to the area of TiDB App development. lgtm needs-1-more-lgtm Indicates a PR needs 1 more LGTM. needs-cherry-pick-master Should cherry pick this PR to master branch. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. translation/from-docs This PR is translated from a PR in pingcap/docs. type/refactor The issue belongs to a refactor work.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants