pingcap/docs: the source of the TiDB manual, versioned by release branch

This repository is the input to the website, not the website

The pingcap/docs repository stores all the source files of the TiDB documentation published on the PingCAP website, and the Chinese-language documentation lives in a separate repository, pingcap/docs-cn. That split is the first thing to understand, because it decides which repository a fix belongs in. The published English site is at docs.pingcap.com/tidb/stable, and the Chinese site at the zh path of the same domain. The README states that the official documentation supports two languages, en and zh, and points out that other languages are available through Google Translate, listing French, Japanese, Korean, German and Spanish versions built from the same English source. So the translation story is deliberately thin, and the real localisation work happens in the separate Chinese repository. The top-level directory listing confirms the shape of the thing. There is no application code, only documentation source, and the files sit at the root as individual Markdown pages such as basic-sql-operations.md, choose-index.md, auto-increment.md, cached-tables.md and cluster-indexes.md, alongside directories for api/, ai/, benchmark/, best-practices/, br/ and clinic/. There are also several TOC files, one per documentation product.

Thirty branches, and only the LTS ones still move

The branch table is the most useful page in the repository, because it tells you which documentation you are reading and whether anyone is still fixing it. The master branch carries the latest development version. Alongside it sit the long-term support branches, which are the ones that keep getting updated: release-8.5 for 8.5 LTS, release-8.1 for 8.1 LTS, release-7.5 for 7.5 LTS, release-7.1 for 7.1 LTS, release-6.5 for 6.5 LTS, and release-6.1, which is marked as LTS but also archived and no longer updated. Every other branch is a development milestone release or an older stable version, and each of those is explicitly marked as archived documentation, no longer updated. The list runs back to release-2.1. So there are two practical consequences. If you are reading the master branch documentation, you are reading behaviour that may not be in any release yet, and if you are on a development milestone branch, the fixes for your version went elsewhere. The right branch to read is the one that matches the server version you run, and for most production installs that will be an LTS branch. The branches are also where the doc versioning work happens: a fix landed on master has to be cherry-picked forward to whichever LTS branches need it, and the table is the map of that effort.

A small Node tool extracts pages from the table of contents

The package.json in the root describes a small utility rather than the documentation site itself. The package is named extract_file_from_toc_md, version 1.0.0, private, ES module, MIT licensed, and its dependency list is the interesting part:

{
  "name": "extract_file_from_toc_md",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT",
  "type": "module",
  "dependencies": {
    "axios": "^1.4.0",
    "glob": "^8.0.3",
    "mdast-util-from-markdown": "^1.2.0",
    "mdast-util-frontmatter": "^1.0.0",
    "mdast-util-gfm": "^2.0.1",
    "mdast-util-mdx": "^2.0.0",
    "mdast-util-to-markdown": "^1.3.0",
    "micromark-extension-frontmatter": "^1.0.0",
    "micromark-extension-gfm": "^2.0.1",
    "micromark-extension-mdxjs": "^1.0.0",
    "octokit": "^3.1.0",
    "unist-util-visit": "^4.1.0"
  },

What this tells you is that the documentation is a Markdown AST problem, not a text problem. The mdast utilities and their micromark counterparts handle the parsing and serialising, GFM and MDX extensions are enabled so that the pages can use GitHub-flavoured and MDX syntax, frontmatter handling is separate, and unist-util-visit walks the tree. axios and glob handle fetching and matching files, and octokit provides GitHub API access, which is consistent with a tool that gathers page lists from the repository and the table of contents file. The dev dependencies are the linting side of the same story: remark-cli with remark-lint, a PingCAP-specific anchor lint rule, markdown-link-check for link validation, and the vale style checker configured by the .vale.ini file in the root.

Vale, markdownlint, lychee and remark are the quality gates

The root of the repository carries a set of configuration files that together describe how a documentation change is checked. A .vale.ini file configures Vale, the prose linter, which is how a manual gets a house style for wording and grammar rather than only for formatting. A .markdownlint.yaml configures markdownlint for structural rules on the Markdown itself, and a .prettier-ignore style convention keeps formatting consistent across contributors. A .lycheeignore lists URLs that the link checker should not attempt, which is necessary because documentation pages reference internal endpoints and generated artefacts that do not exist on the public internet. The remark and remark-lint dev dependencies add a Markdown-aware linter with a PingCAP-specific rule for anchors, which catches the case where a heading changes and a link pointing at that heading silently stops working. There are also .coderabbit.yaml, .gemini/ and .vaunt/ directories and an AGENTS.md file, plus an OWNERS file with an OWNERS_ALIASES file, which is the mechanism that assigns review responsibility for particular areas of the documentation. The pattern is the familiar one from large documentation projects: the prose checks catch writing problems that a compiler would catch in code, and the link and anchor checks catch the specific failure mode of documentation, which is links that quietly rot.

PDF output is a supported customisation path

The README flags one use case that is not about writing docs at all. If you want to locally customise and output the TiDB documentation in PDF format, for scenarios such as freely sorting or deleting certain contents, the README points to a dedicated tutorial in the repository, the TiDB Documentation PDF Generation Tutorial under resources. That is a notable feature for a database manual, because a PDF is a different artefact with different constraints. Documentation written for a website assumes a reader can click through, search, and follow a link to a concept defined elsewhere. A PDF has one direction of travel, and it needs a table of contents that works on a page. The tutorial therefore matters to anyone who has been handed a request to produce a self-contained handbook of TiDB for a customer or a course, which is otherwise a miserable manual job. The TOC files at the root are the same files that would drive such a build, with separate tables of contents for the API reference, for AI features, for best practices, for development, and for the TiDB Cloud tiers, and separate ones for the releases. The repository also carries a release-agnostic _index.md and _docHome.md, which are the entry points the site assembles its landing pages from.

Contributing is issue-first, and the licence is not a standard one

The contribution path in the README is short. If you find documentation issues, you can create an Issue to let the team know, or go directly to a Pull Request, with the contributing guide at CONTRIBUTING.md explaining how to contribute. The README also links a contribution map image in the media directory and points at the contributor credits file, both of which suggest the project tracks who wrote which section. The topics include hacktoberfest, so the repository takes outside contributions in that setting. The licence deserves a note. The repository's licence field is listed as a custom licence that GitHub cannot classify, and the file to read is LICENSE at the root. That is worth checking before you reuse any of the text, because the documentation content is the product here and the terms attached to it are what govern how a company can lift a page into its own internal wiki. The project publishes exactly one release, an RC4 release tagged in 2017, which tells you the release history of this repository is not the release history of TiDB. TiDB versions are tracked by branch here, and the last push to the repository was on 2026-10-20, so the documentation is being worked on continuously even though the repository itself has no recent tags.

Editorial conclusion

pingcap/docs suits someone who wants to contribute to the TiDB manual, who needs to build a PDF of the documentation for a specific scenario, or who wants to see how a large product keeps versioned documentation in step with its releases. It is the wrong choice if you are looking for the TiDB database itself, since this repository holds only the documentation source, and it is the wrong choice if you need a single current manual, since the text you want is on the website while this repository is only the input to it. Verify first which branch matches the TiDB version you actually run, since the archived branches are no longer updated, and read the contributing guide before opening a pull request.

Frequently asked questions

Official sources

1. Issues
2. pingcap/docs on GitHub
3. Project website
4. README
5. Releases