Step 2. Update content

In the pingcap-docsite-preview context, content refers to all documents on PingCAP documentation website. You can update content in the following ways:

Automatically update from a pull request
Automatically update from multiple pull requests
Manually update

To maintain continuous synchronization with pull requests, you can schedule periodic updates using GitHub Actions.

Update from a pull request

You can automatically update the preview content from a pull request by creating a new branch.

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

Create a pull request to one of the following repositories:

In your fork, create a new branch from the main branch following these naming conventions:

Documentation	Branch naming convention
TiDB (English)	`preview/pingcap/docs/{PR_NUMBER}`
TiDB (Chinese)	`preview/pingcap/docs-cn/{PR_NUMBER}`
TiDB Cloud	`preview-cloud/pingcap/docs/{PR_NUMBER}`
TiDB Operator	`preview-operator/pingcap/docs-tidb-operator/{PR_NUMBER}`

The sync_pr.yml workflow is automatically triggered to update the content from the pull request.
For periodic updates to this branch, see Perform periodic updates.

4. To deploy your changes to a preview website, see Deploy the preview website.

Prerequisites

Make sure that you have met the following requirements:

Install jq.
Generate a GitHub personal access token with the repo scope and set it as the GITHUB_TOKEN environment variable value.

Create a pull request to one of the following repositories:

In your fork, create a new branch from the main branch following these naming conventions:

Documentation	Branch naming convention
TiDB (English)	`preview/pingcap/docs/{PR_NUMBER}`
TiDB (Chinese)	`preview/pingcap/docs-cn/{PR_NUMBER}`
TiDB Cloud	`preview-cloud/pingcap/docs/{PR_NUMBER}`
TiDB Operator	`preview-operator/pingcap/docs-tidb-operator/{PR_NUMBER}`

git clone https://github.com/Oreoxmt/pingcap-docsite-preview.git
cd pingcap-docsite-preview
git checkout -b preview/pingcap/docs/{PR_NUMBER}

Execute the sync_pr.sh script to update the content from the pull request.
./sync_pr.sh
This script automatically synchronizes document changes from the pull request and commits them to the current branch. To update the remote branch with these changes, be sure to push the commit.

4. To deploy your changes to a preview website, see Deploy the preview website.

Update from multiple pull requests

You can automatically update the preview content from multiple pull requests by creating a new branch and configuring it.

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

Create pull requests to the following repositories:
In your fork, create a new branch from the main branch. Do not include a preview prefix in the branch name.
Update the configuration in the sync_mult_prs.sh script:
To preview the following pull requests: pingcap/docs/1234 for TiDB, pingcap/docs-cn/1234 for TiDB, pingcap/docs/5678 for TiDB Cloud, and pingcap/docs-tidb-operator/1234 for TiDB Operator, configure as follows:
./sync_pr.sh preview/pingcap/docs/1234 ./sync_pr.sh preview/pingcap/docs-cn/1234 ./sync_pr.sh preview-cloud/pingcap/docs/5678 ./sync_pr.sh preview-operator/pingcap/docs-tidb-operator/1234
pingcap-docsite-preview updates documents based on pull requests in the sequence of the preceding commands. If a file undergoes modifications in multiple pull requests, its content gets updated from the pull request specified later in the script.
By default, pull requests are previewed in their respective base branches. To preview in a different version, such as v1.0, when the base branch of these pull requests is master, configure as follows:
rsync -av markdown-pages/zh/tidb/master/ markdown-pages/zh/tidb/release-1.0/ rsync -av markdown-pages/en/tidb/master/ markdown-pages/en/tidb/release-1.0/ rsync -av markdown-pages/en/tidb-in-kubernetes/master/ markdown-pages/en/tidb-in-kubernetes/release-1.0/ rsync -av markdown-pages/zh/tidb-in-kubernetes/master/ markdown-pages/zh/tidb-in-kubernetes/release-1.0/
Manually trigger the sync_mult_prs.yml workflow for multi-pr-preview branch. Then, the workflow updates the content from these pull requests.
For periodic updates to this branch, see Perform periodic updates.

5. To deploy your changes to a preview website, see Deploy the preview website.

Prerequisites

Make sure that you have met the following requirements:

Install jq.
Generate a GitHub personal access token with the repo scope and set it as the GITHUB_TOKEN environment variable value.

Create pull requests to the following repositories:
In your fork, create a new branch from the main branch. Do not include a preview prefix in the branch name.
git clone https://github.com/Oreoxmt/pingcap-docsite-preview.git cd pingcap-docsite-preview git checkout -b multi-pr-preview
Update the configuration in the sync_mult_prs.sh script:
To preview the following pull requests: pingcap/docs/1234 for TiDB, pingcap/docs-cn/1234 for TiDB, pingcap/docs/5678 for TiDB Cloud, and pingcap/docs-tidb-operator/1234 for TiDB Operator, configure as follows:
./sync_pr.sh preview/pingcap/docs/1234 ./sync_pr.sh preview/pingcap/docs-cn/1234 ./sync_pr.sh preview-cloud/pingcap/docs/5678 ./sync_pr.sh preview-operator/pingcap/docs-tidb-operator/1234
pingcap-docsite-preview updates documents based on pull requests in the sequence of the preceding commands. If a file undergoes modifications in multiple pull requests, its content gets updated from the pull request specified later in the script.
By default, pull requests are previewed in their respective base branches. To preview in a different version, such as v1.0, when the base branch of these pull requests is master, configure as follows:
rsync -av markdown-pages/zh/tidb/master/ markdown-pages/zh/tidb/release-1.0/ rsync -av markdown-pages/en/tidb/master/ markdown-pages/en/tidb/release-1.0/ rsync -av markdown-pages/en/tidb-in-kubernetes/master/ markdown-pages/en/tidb-in-kubernetes/release-1.0/ rsync -av markdown-pages/zh/tidb-in-kubernetes/master/ markdown-pages/zh/tidb-in-kubernetes/release-1.0/
Execute the sync_mult_prs.sh script to update the content from these pull requests.
./sync_mult_prs.sh
This script automatically synchronizes document changes from pull requests and commits them to the current branch. To update the remote branch with these changes, be sure to push the commits.
For periodic updates to this branch, see Perform periodic updates.

5. To deploy your changes to a preview website, see Deploy the preview website.

Perform periodic updates

You can use the sync_scheduler.yml GitHub workflow to periodically update the preview content from a pull request and multiple pull requests.

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

Suppose you have created a branch preview/pingcap/docs/1234 to preview a PR and created a branch multi-pr-preview to preview multiple PRs. To periodically update preview/pingcap/docs/1234 every 1 hour and multi-pr-preview every 6 hours, configure the sync_scheduler.yml workflow in your default branch as follows:

name: Sync docs on schedule

on:
  schedule:
    - cron: "0 */1 * * *" # every 1 hour
    - cron: "0 */6 * * *" # every 6 hours

jobs:
  sync_scheduler:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      actions: write
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

    steps:
      - name: Checkout current repo
        uses: actions/checkout@v3
    
      - name: Sync preview branch every 1 hour
        if: github.event_name == 'schedule' && github.event.schedule == '0 */1 * * *'
        run: |
          gh workflow run sync_pr.yml --ref preview/pingcap/docs/1234
    
      - name: Sync preview branch (multiple PRs) every 6 hours
        if: github.event_name == 'schedule' && github.event.schedule == '0 */6 * * *'
        run: |
          gh workflow run sync_mult_prs.yml --ref multi-pr-preview

For more information, refer to Workflow syntax for GitHub Actions.

Perform a manual update

Clone your fork, change to the directory, and create a new branch:
git clone https://github.com/Oreoxmt/pingcap-docsite-preview.git cd pingcap-docsite-preview git checkout -b test-manual-update
Optional: Update the scaffold:
./sync_scaffold.sh [BRANCH|COMMIT]
Place the files you want to preview under the markdown-pages directory according to the following structure:
. ├── en │ ├── tidb │ │ ├── master │ │ ├── release-x.y │ ├── tidb-in-kubernetes │ │ ├── master │ │ ├── release-x.y │ └── tidbcloud │ └── master └── zh ├── tidb │ ├── master │ ├── release-x.y └── tidb-in-kubernetes ├── master ├── release-x.y
It is recommended to keep the original folder structure, so you can replace docs.pingcap.com with http://localhost:8000/ to get an instant preview without guessing the URL.
For example, it is best to put dashboard/top-sql.md under en/tidb/master/dashboard/top-sql.md.
Optional: To make the render keep consistent with the official website, you need to manually remove all {{< copyable "..." >}} strings in Markdown files.

5. To deploy your changes to a preview website, see Deploy the preview website.

Last modified: 01 April 2025