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

.github/workflows/ci.yaml

@@ -7,51 +7,58 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  tidb-check:
+  duplicated-file-names:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out
+        uses: actions/checkout@v4
+      - name: Verify duplicated file names
+        run: ./scripts/verify-duplicated-file-name.sh
+
+  internal-links-files:
     runs-on: ubuntu-latest
     steps:
       - name: Check out
         uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
           node-version: "18"
-      - name: Verify duplicated file names
-        run: ./scripts/verify-duplicated-file-name.sh
-      - name: Verify internal links and anchors - tidb only
-        run: |
-          npm i
-          node ./scripts/filterNonCloudDoc.js
-          cp -r ./scripts ./tmp
-          cp -r ./media ./tmp
-          cp .gitignore ./tmp/
-          cd ./tmp
-          ./scripts/verify-links.sh
-          ./scripts/verify-link-anchors.sh
+          cache: npm
+          cache-dependency-path: package-lock.json
+      - name: Install Node dependencies
+        run: npm ci
+      - name: Verify internal links (full repo) - files
+        run: ./scripts/verify-links.sh
 
-  tidb-cloud-check:
+  internal-links-anchors:
     runs-on: ubuntu-latest
     steps:
       - name: Check out
         uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
           node-version: "18"
-      - name: Check TOC-tidb-cloud.md existence
-        id: check_cloud_toc
-        uses: andstor/file-existence-action@v2
+          cache: npm
+          cache-dependency-path: package-lock.json
+      - name: Install Node dependencies
+        run: npm ci
+      - name: Verify internal links (full repo) - anchors
+        run: ./scripts/verify-link-anchors.sh
+
+  internal-links-toc:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out
+        uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
-          files: "TOC-tidb-cloud.md"
-      - name: Verify internal links - cloud only
-        if: steps.check_cloud_toc.outputs.files_exists == 'true'
-        run: |
-          npm i
-          node ./scripts/filterCloudDoc.js
-          cp -r ./scripts ./tmp
-          cp -r ./media ./tmp
-          cp .gitignore ./tmp/
-          cd ./tmp
-          ./scripts/verify-links.sh
-          ./scripts/verify-link-anchors.sh
+          node-version: "18"
+          cache: npm
+          cache-dependency-path: package-lock.json
+      - name: Install Node dependencies
+        run: npm ci
+      - name: Verify internal links (full repo) - TOC membership
+        run: node ./scripts/verify-internal-links-in-toc.js
 
   vale:
     runs-on: ubuntu-latest

.github/workflows/dispatch-nextgen.yml

@@ -0,0 +1,31 @@
+name: Trigger docs-staging nextgen update
+
+on:
+  push:
+    paths-ignore:
+      - ".github/**"
+    branches:
+      - feature/preview-top-navigation
+
+jobs:
+  trigger:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: trigger docs-staging update-nextgen workflow
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.DOCS_STAGING }}
+          script: |
+            await github.rest.actions.createWorkflowDispatch({
+              owner: 'pingcap',
+              repo: 'docs-staging',
+              workflow_id: 'update-nextgen.yml',
+              ref: 'nextgen',
+              inputs: {
+                repo: 'pingcap/docs',
+                branch: 'feature/preview-top-navigation'
+              }
+            })

TOC-ai.md

@@ -0,0 +1,86 @@
+<!-- markdownlint-disable MD007 -->
+<!-- markdownlint-disable MD041 -->
+
+# Table of Contents
+
+## QUICK START
+
+- [Get Started via Python](/ai/quickstart-via-python.md)
+- [Get Started via SQL](/ai/quickstart-via-sql.md)
+
+## CONCEPTS
+
+- [Vector Search](/ai/concepts/vector-search-overview.md)
+
+## GUIDES
+
+- [Connect to TiDB](/ai/guides/connect.md)
+- [Working with Tables](/ai/guides/tables.md)
+- Search Features
+  - [Vector Search](/ai/guides/vector-search.md)
+  - Full-Text Search
+    - [Full-Text Search via Python](/ai/guides/vector-search-full-text-search-python.md)
+    - [Full-Text Search via SQL](/ai/guides/vector-search-full-text-search-sql.md)
+  - [Hybrid Search](/ai/guides/vector-search-hybrid-search.md)
+  - [Image Search](/ai/guides/image-search.md)
+- Advanced Features
+  - [Auto Embedding](/ai/guides/auto-embedding.md)
+  - [Filtering](/ai/guides/filtering.md)
+  - [Reranking](/ai/guides/reranking.md)
+  - [Join Queries](/ai/guides/join-queries.md)
+  - [Raw SQL Queries](/ai/guides/raw-queries.md)
+  - [Transactions](/ai/guides/transactions.md)
+
+## EXAMPLES
+
+- [Basic CRUD Operations](/ai/examples/basic-with-pytidb.md)
+- [Auto Embedding](/ai/examples/auto-embedding-with-pytidb.md)
+- Search & Retrieval
+  - [Vector Search](/ai/examples/vector-search-with-pytidb.md)
+  - [Full-Text Search](/ai/examples/fulltext-search-with-pytidb.md)
+  - [Hybrid Search](/ai/examples/hybrid-search-with-pytidb.md)
+  - [Image Search](/ai/examples/image-search-with-pytidb.md)
+- AI Applications
+  - [RAG Application](/ai/examples/rag-with-pytidb.md)
+  - [Conversational Memory](/ai/examples/memory-with-pytidb.md)
+  - [Text-to-SQL](/ai/examples/text2sql-with-pytidb.md)
+
+## INTEGRATIONS
+
+- [Integration Overview](/ai/integrations/vector-search-integration-overview.md)
+- Auto Embedding
+  - [Overview](/ai/integrations/vector-search-auto-embedding-overview.md)
+  - [OpenAI](/ai/integrations/vector-search-auto-embedding-openai.md)
+  - [OpenAI Compatible](/ai/integrations/embedding-openai-compatible.md)
+  - [Jina AI](/ai/integrations/vector-search-auto-embedding-jina-ai.md)
+  - [Cohere](/ai/integrations/vector-search-auto-embedding-cohere.md)
+  - [Google Gemini](/ai/integrations/vector-search-auto-embedding-gemini.md)
+  - [Hugging Face](/ai/integrations/vector-search-auto-embedding-huggingface.md)
+  - [NVIDIA NIM](/ai/integrations/vector-search-auto-embedding-nvidia-nim.md)
+  - [Amazon Titan](/ai/integrations/vector-search-auto-embedding-amazon-titan.md)
+- AI Frameworks
+  - [LangChain](/ai/integrations/vector-search-integrate-with-langchain.md)
+  - [LlamaIndex](/ai/integrations/vector-search-integrate-with-llamaindex.md)
+- ORM Libraries
+  - [SQLAlchemy](/ai/integrations/vector-search-integrate-with-sqlalchemy.md)
+  - [Django ORM](/ai/integrations/vector-search-integrate-with-django-orm.md)
+  - [Peewee](/ai/integrations/vector-search-integrate-with-peewee.md)
+- Cloud Services
+  - [Jina AI Embedding](/ai/integrations/vector-search-integrate-with-jinaai-embedding.md)
+  - [Amazon Bedrock](/ai/integrations/vector-search-integrate-with-amazon-bedrock.md)
+- MCP Server
+  - [Overview](/ai/integrations/tidb-mcp-server.md)
+  - [Claude Code](/ai/integrations/tidb-mcp-claude-code.md)
+  - [Claude Desktop](/ai/integrations/tidb-mcp-claude-desktop.md)
+  - [Cursor](/ai/integrations/tidb-mcp-cursor.md)
+  - [VS Code](/ai/integrations/tidb-mcp-vscode.md)
+  - [Windsurf](/ai/integrations/tidb-mcp-windsurf.md)
+
+## REFERENCE
+
+- [Vector Data Types](/ai/reference/vector-search-data-types.md)
+- [Functions and Operators](/ai/reference/vector-search-functions-and-operators.md)
+- [Vector Search Index](/ai/reference/vector-search-index.md)
+- [Performance Tuning](/ai/reference/vector-search-improve-performance.md)
+- [Limitations](/ai/reference/vector-search-limitations.md)
+- [Changelogs](/ai/reference/vector-search-changelogs.md)

TOC-api.md

@@ -0,0 +1,18 @@
+<!-- markdownlint-disable MD007 -->
+<!-- markdownlint-disable MD041 -->
+
+# Table of Contents
+
+## TIDB CLOUD
+
+- [API Overview](/api/tidb-cloud-api-overview.md)
+- [API v1beta1](/api/tidb-cloud-api-v1beta1.md)
+- [API v1beta](/api/tidb-cloud-api-v1beta.md)
+
+## TIDB SELF-MANAGED
+
+- [TiProxy API](/api/tiproxy-api-overview.md)
+- [Data Migration API](/api/dm-api-overview.md)
+- [Monitoring API](/api/monitoring-api-overview.md)
+- [TiCDC API](/api/ticdc-api-overview.md)
+- [TiDB Operator API](/api/tidb-operator-api-overview.md)

TOC-best-practices.md

@@ -0,0 +1,35 @@
+<!-- markdownlint-disable MD007 -->
+<!-- markdownlint-disable MD041 -->
+
+# Table of Contents
+
+## Overview
+
+- [Use TiDB](/best-practices/tidb-best-practices.md)
+
+## Schema Design
+
+- [Manage DDL](/best-practices/ddl-introduction.md)
+- [Use UUIDs as Primary Keys](/best-practices/uuid.md)
+- [Use TiDB Partitioned Tables](/best-practices/tidb-partitioned-tables-best-practices.md)
+- [Optimize Multi-Column Indexes](/best-practices/multi-column-index-best-practices.md)
+- [Manage Indexes and Identify Unused Indexes](/best-practices/index-management-best-practices.md)
+
+## Deployment
+
+- [Deploy TiDB on Public Cloud](/best-practices/best-practices-on-public-cloud.md)
+- [Three-Node Hybrid Deployment](/best-practices/three-nodes-hybrid-deployment.md)
+- [Local Reads in Three-Data-Center Deployments](/best-practices/three-dc-local-read.md)
+
+## Operations
+
+- [Use HAProxy for Load Balancing](/best-practices/haproxy-best-practices.md)
+- [Use Read-Only Storage Nodes](/best-practices/readonly-nodes.md)
+- [Monitor TiDB Using Grafana](/best-practices/grafana-monitor-best-practices.md)
+
+## Performance Tuning
+
+- [Handle Millions of Tables in SaaS Multi-Tenant Scenarios](/best-practices/saas-best-practices.md)
+- [Handle High-Concurrency Writes](/best-practices/high-concurrency-best-practices.md)
+- [Tune TiKV Performance with Massive Regions](/best-practices/massive-regions-best-practices.md)
+- [Tune PD Scheduling](/best-practices/pd-scheduling-best-practices.md)

TOC-develop.md

@@ -0,0 +1,119 @@
+<!-- markdownlint-disable MD007 -->
+<!-- markdownlint-disable MD041 -->
+
+# Table of Contents
+
+## QUICK START
+
+- [Create a {{{ .starter }}} Cluster](/develop/dev-guide-build-cluster-in-cloud.md)
+- [TiDB Basics](/develop/dev-guide-tidb-basics.md)
+- [CRUD SQL in TiDB](/develop/dev-guide-tidb-crud-sql.md)
+
+## GUIDES
+
+- Connect to TiDB
+  - [Overview](/develop/dev-guide-connect-to-tidb.md)
+  - CLI & GUI Tools
+    - [MySQL CLI Tools](/develop/dev-guide-mysql-tools.md)
+    - [JetBrains DataGrip](/develop/dev-guide-gui-datagrip.md)
+    - [DBeaver](/develop/dev-guide-gui-dbeaver.md)
+    - [VS Code](/develop/dev-guide-gui-vscode-sqltools.md)
+    - [MySQL Workbench](/develop/dev-guide-gui-mysql-workbench.md)
+    - [Navicat](/develop/dev-guide-gui-navicat.md)
+  - Drivers & ORMs
+    - [Choose a Driver or ORM](/develop/dev-guide-choose-driver-or-orm.md)
+    - Java
+      - [JDBC](/develop/dev-guide-sample-application-java-jdbc.md)
+      - [MyBatis](/develop/dev-guide-sample-application-java-mybatis.md)
+      - [Hibernate](/develop/dev-guide-sample-application-java-hibernate.md)
+      - [Spring Boot](/develop/dev-guide-sample-application-java-spring-boot.md)
+      - [Configure Connection Pools and Connection Parameters](/develop/dev-guide-connection-parameters.md)
+      - [Best Practices for Developing Java Applications](/develop/java-app-best-practices.md)
+    - Go
+      - [Go-MySQL-Driver](/develop/dev-guide-sample-application-golang-sql-driver.md)
+      - [GORM](/develop/dev-guide-sample-application-golang-gorm.md)
+    - Python
+      - [mysqlclient](/develop/dev-guide-sample-application-python-mysqlclient.md)
+      - [MySQL Connector/Python](/develop/dev-guide-sample-application-python-mysql-connector.md)
+      - [PyMySQL](/develop/dev-guide-sample-application-python-pymysql.md)
+      - [SQLAlchemy](/develop/dev-guide-sample-application-python-sqlalchemy.md)
+      - [peewee](/develop/dev-guide-sample-application-python-peewee.md)
+      - [Django](/develop/dev-guide-sample-application-python-django.md)
+    - Node.js
+      - [node-mysql2](/develop/dev-guide-sample-application-nodejs-mysql2.md)
+      - [mysql.js](/develop/dev-guide-sample-application-nodejs-mysqljs.md)
+      - [Prisma](/develop/dev-guide-sample-application-nodejs-prisma.md)
+      - [Sequelize](/develop/dev-guide-sample-application-nodejs-sequelize.md)
+      - [TypeORM](/develop/dev-guide-sample-application-nodejs-typeorm.md)
+      - [Next.js](/develop/dev-guide-sample-application-nextjs.md)
+      - [AWS Lambda](/develop/dev-guide-sample-application-aws-lambda.md)
+    - Ruby
+      - [mysql2](/develop/dev-guide-sample-application-ruby-mysql2.md)
+      - [Rails](/develop/dev-guide-sample-application-ruby-rails.md)
+    - C#
+      - [C#](/develop/dev-guide-sample-application-cs.md)
+  - TiDB Cloud Serverless Driver ![BETA](/media/tidb-cloud/blank_transparent_placeholder.png)
+    - [Overview](/develop/serverless-driver.md)
+    - [Node.js Example](/develop/serverless-driver-node-example.md)
+    - [Prisma Example](/develop/serverless-driver-prisma-example.md)
+    - [Kysely Example](/develop/serverless-driver-kysely-example.md)
+    - [Drizzle Example](/develop/serverless-driver-drizzle-example.md)
+- Design Database Schema
+  - [Overview](/develop/dev-guide-schema-design-overview.md)
+  - [Create a Database](/develop/dev-guide-create-database.md)
+  - [Create a Table](/develop/dev-guide-create-table.md)
+  - [Create a Secondary Index](/develop/dev-guide-create-secondary-indexes.md)
+- Write Data
+  - [Insert Data](/develop/dev-guide-insert-data.md)
+  - [Update Data](/develop/dev-guide-update-data.md)
+  - [Delete Data](/develop/dev-guide-delete-data.md)
+  - [Periodically Delete Expired Data Using TTL (Time to Live)](/time-to-live.md)
+  - [Prepared Statements](/develop/dev-guide-prepared-statement.md)
+- Read Data
+  - [Query Data from a Single Table](/develop/dev-guide-get-data-from-single-table.md)
+  - [Multi-table Join Queries](/develop/dev-guide-join-tables.md)
+  - [Subquery](/develop/dev-guide-use-subqueries.md)
+  - [Paginate Results](/develop/dev-guide-paginate-results.md)
+  - [Views](/develop/dev-guide-use-views.md)
+  - [Temporary Tables](/develop/dev-guide-use-temporary-tables.md)
+  - [Common Table Expression](/develop/dev-guide-use-common-table-expression.md)
+  - Read Replica Data
+    - [Follower Read](/develop/dev-guide-use-follower-read.md)
+    - [Stale Read](/develop/dev-guide-use-stale-read.md)
+  - [HTAP Queries](/develop/dev-guide-hybrid-oltp-and-olap-queries.md)
+- [Vector Search](/develop/dev-guide-vector-search.md) ![BETA](/media/tidb-cloud/blank_transparent_placeholder.png)
+- Manage Transactions
+  - [Overview](/develop/dev-guide-transaction-overview.md)
+  - [Optimistic and Pessimistic Transactions](/develop/dev-guide-optimistic-and-pessimistic-transaction.md)
+  - [Transaction Restraints](/develop/dev-guide-transaction-restraints.md)
+  - [Handle Transaction Errors](/develop/dev-guide-transaction-troubleshoot.md)
+- Optimize
+  - [Overview](/develop/dev-guide-optimize-sql-overview.md)
+  - [SQL Performance Tuning](/develop/dev-guide-optimize-sql.md)
+  - [Best Practices for Performance Tuning](/develop/dev-guide-optimize-sql-best-practices.md)
+  - [Best Practices for Indexing](/develop/dev-guide-index-best-practice.md)
+  - Additional Optimization Methods
+    - [Avoid Implicit Type Conversions](/develop/dev-guide-implicit-type-conversion.md)
+    - [Unique Serial Number Generation](/develop/dev-guide-unique-serial-number-generation.md)
+- Troubleshoot
+  - [SQL or Transaction Issues](/develop/dev-guide-troubleshoot-overview.md)
+  - [Unstable Result Set](/develop/dev-guide-unstable-result-set.md)
+  - [Timeouts](/develop/dev-guide-timeouts-in-tidb.md)
+
+## INTEGRATIONS
+
+- Third-Party Support
+  - [Third-Party Tools Supported by TiDB](/develop/dev-guide-third-party-support.md)
+  - [Known Incompatibility Issues with Third-Party Tools](/develop/dev-guide-third-party-tools-compatibility.md)
+- [ProxySQL](/develop/dev-guide-proxysql-integration.md)
+- [Amazon AppFlow](/develop/dev-guide-aws-appflow-integration.md)
+- [WordPress](/develop/dev-guide-wordpress.md)
+
+## REFERENCE
+
+- Development Guidelines
+  - [Object Naming Convention](/develop/dev-guide-object-naming-guidelines.md)
+  - [SQL Development Specifications](/develop/dev-guide-sql-development-specification.md)
+- [Bookshop Example Application](/develop/dev-guide-bookshop-schema-design.md)
+- Cloud Native Development Environment
+  - [Gitpod](/develop/dev-guide-playground-gitpod.md)