Step 1. Update scaffold

This document introduces what the scaffold is and how to update it.

Concept

In the pingcap-docsite-preview context, scaffold refers to a specific set of elements synchronized from pingcap/docs-staging. These elements are crucial for the structure and navigation of the documentation website. It contains the following elements:

Version selection: the docs.json file
Table of contents: all TOC.md files in the markdown-pages directory
Index pages: all _index.md files in the markdown-pages directory
Homepage: all _docHome.md files in the markdown-pages directory

An example of the scaffold

.
├── docs.json
├── markdown-pages
│   ├── en
│   │     ├── tidb
│   │     │     ├── master
│   │     │     │     ├── TOC.md
│   │     │     │     ├── _docHome.md
│   │     │     │     └── _index.md
│   │     │     ├── release-x.y
│   │     │     │     ├── TOC.md
│   │     │     │     └── _index.md
│   │     ├── tidb-in-kubernetes
│   │     │     ├── master
│   │     │     │     ├── TOC.md
│   │     │     │     └── _index.md
│   │     │     ├── release-x.y
│   │     │     │     ├── TOC.md
│   │     │     │     └── _index.md
│   │     └── tidbcloud
│   │         └── master
│   │             ├── TOC.md
│   │             └── tidb-cloud
│   │                 └── _index.md
│   └── zh
│       ├── tidb
│       │     ├── master
│       │     │     ├── TOC.md
│       │     │     ├── _docHome.md
│       │     │     └── _index.md
│       │     ├── release-x.y
│       │     │     ├── TOC.md
│       │     │     └── _index.md
│       └── tidb-in-kubernetes
│           ├── master
│           │     ├── TOC.md
│           │     └── _index.md
│           ├── release-x.y
│           │     ├── TOC.md
│           │     └── _index.md

Update the scaffold in GitHub Actions

Make sure that you have enabled GitHub Actions for your fork.

In your fork, the sync_scaffold.yml workflow can be manually triggered (workflow_dispatch) or automatically triggered every 15 days (0 0 */15 * *) by default.
on: workflow_dispatch: schedule: - cron: "0 0 */15 * *"
To modify the schedule event or add more events to trigger the workflow, you can adjust the value of on in the sync_scaffold.yml file.
For more information, see Events that trigger workflows.

Update the scaffold locally

To update the scaffold of your fork on your local machine, you can execute the sync_scaffold.sh script.
This script automatically updates the scaffold to the latest version from pingcap/docs-staging.
To update the scaffold to a specific version, you can specify a branch or commit in sync_scaffold.sh.
Examples:
git clone https://github.com/Oreoxmt/pingcap-docsite-preview.git cd pingcap-docsite-preview ./sync_scaffold.sh
git clone https://github.com/Oreoxmt/pingcap-docsite-preview.git cd pingcap-docsite-preview ./sync_scaffold.sh $BRANCH
git clone https://github.com/Oreoxmt/pingcap-docsite-preview.git cd pingcap-docsite-preview ./sync_scaffold.sh $COMMIT

Last modified: 05 September 2025