# Discover PingCAP Docsite Preview Explore PingCAP Docsite Preview Preview changes to the PingCAP documentation website before merging pull requests. # Overview [pingcap-docsite-preview](https://github.com/Oreoxmt/pingcap-docsite-preview) is a tool designed for previewing changes to [PingCAP documentation website](https://docs.pingcap.com) before merging pull requests. It enables you to: * Validate document updates without affecting the official website. * Collaborate with reviewers by sharing a preview link. * Verify the accurate rendering of changes before merging them into the production website. * Achieve consistent preview results that match the official website. Procedure: Key features * Ease of use: preview a PR by simply creating a new branch. * Cross-repository preview: simultaneously preview changes from multiple PRs across different repositories. * Centralized preview schedule management: organize and manage preview schedules in a unified workflow. * Customizability: customize the preview process to meet your requirements. Procedure: Scope Procedure: Usage scenarios * [Preview and validate minor changes in 2 minutes.](usage-scenarios.html#local-preview-for-minor-changes) * [Preview a PR and collaborate with reviewers.](usage-scenarios.html#preview-a-pr) * [Preview multiple PRs across different repositories.](usage-scenarios.html#preview-multiple-pr-changes) Procedure: Steps to preview document changes 1. Fork the [pingcap-docsite-preview](https://github.com/Oreoxmt/pingcap-docsite-preview) repository. 2. Update the scaffold of [PingCAP documentation website](https://docs.pingcap.com), including version selection, table of contents, index pages, and the homepage. For more information, see [Update scaffold](update-scaffold.html). 3. Update the documentation content you want to preview. For more information, see [Update content](update-content.html). 4. Deploy the preview website either locally or on a static hosting service. For more information, see [Deploy your website](deploy-docsite.html). # Usage Scenarios This document outlines common scenarios for using [pingcap-docsite-preview](https://github.com/Oreoxmt/pingcap-docsite-preview). * [Local preview for minor changes](#local-preview-for-minor-changes) * Quickly preview and validate minor changes affecting one or two documents without images. * Manually update the documents to be previewed. * Preview in 2 minutes. * Setup environment, such as Node.js, pnpm, and Git. * [Collaborative PR preview](#preview-a-pr): * Preview a and collaborate with reviewers. * Automatically update the documents to be previewed. * Preview by creating a new branch in your . * [Preview multiple PR changes](#preview-multiple-pr-changes): * Preview multiple PRs across different repositories at the same time. * Automatically update the documents to be previewed. * Preview by creating and configuring a new branch in your fork. ## Local preview for minor changes Scenario: quickly preview and validate minor changes affecting one or two documents without images. Procedure: Initial setup 1. Make sure that you have installed the following tools: * [Node.js 22 or later](https://nodejs.org/en/download/) * [pnpm](https://pnpm.io/installation) * [Git](https://git-scm.com/downloads) 2. Create a fork of [pingcap-docsite-preview](https://github.com/Oreoxmt/pingcap-docsite-preview). 3. Clone the fork to your local machine. ```SHELL git clone https://github.com/Oreoxmt/pingcap-docsite-preview.git ``` Procedure: Steps 1. Change to your directory and create a new branch. ```SHELL cd pingcap-docsite-preview git checkout -b test-manual-update ``` 2. Optional: Update the scaffold to the latest version if needed. ```SHELL ./sync_scaffold.sh ``` 3. Place the files you want to preview under the `markdown-pages` directory. For example, to preview [https://docs.pingcap.com/tidb/dev/overview](https://docs.pingcap.com/tidb/dev/overview), add the file `markdown-pages/en/tidb/master/overview.md`. For more information, see [Perform a manual update](update-content.html#perform-a-manual-update). 4. Run the following command to preview your changes locally. ```SHELL ./build.sh dev ``` 5. Open the preview URL in your browser. For example, [http://localhost:8000](http://localhost:8000). For more information, see [Deploy the documentation website locally](deploy-local.html). ## Preview a PR Scenario: preview a and collaborate with reviewers. Procedure: Initial setup 1. Create a fork of [pingcap-docsite-preview](https://github.com/Oreoxmt/pingcap-docsite-preview). Make sure that you have enabled GitHub Actions for your fork. : ![Enable GitHub Actions for your repository](images/enable_gha.png) 2. Connect your fork to a cloud service. This document uses [Vercel](https://vercel.com) as an example: 1. Log in to [Vercel](https://vercel.com). 2. In the Overview page, click Add New... > Project. 3. In the Import Git Repository page, search for your (`pingcap-docsite-preview`) and click Import. 4. In the Configure Project page, fill in the following information: * Root Directory: leave it as `./` * Build and Output Settings > Build Command: `./build.sh` * Build and Output Settings > Output Directory: `website-docs/public` * Environment Variables: add a variable with the name `ENABLE_EXPERIMENTAL_COREPACK` and the value `1`. For more information, see [Configuring a Build: Corepack](https://vercel.com/docs/builds/configure-a-build#corepack). 5. Click Deploy. 6. After approximately 5 minutes, the website is deployed. You can get the preview URL from your Vercel project page. For more information, refer to [Deploy the preview website](deploy-docsite.html). Procedure: Steps 1. Optional: Manually trigger the [sync_scaffold.yml](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/main/.github/workflows/sync_scaffold.yml) workflow for the `main` branch of your . 2. In your fork, create a new branch `preview/pingcap/docs/1234` from the `main` branch. 3. The [sync_pr.yml](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/main/.github/workflows/sync_pr.yml) workflow is automatically triggered. You can view the website deployment status in the [Deployments](https://vercel.com/docs/projects/project-dashboard#deployments) page of your Vercel project. 4. Optional: To maintain continuous synchronization with this PR, you can [periodically update](update-content.html#perform-periodic-updates) the content using GitHub Actions. For example, to update `preview/pingcap/docs/1234` branch every 1 hour, configure the [sync_scheduler.yml](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/main/.github/workflows/sync_scheduler.yml) workflow in your default branch as follows: ```YAML name: Sync docs on schedule on: schedule: - cron: "0 */1 * * *" # every 1 hour 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 ``` ## Preview multiple PR changes Scenario: preview multiple across different repositories at the same time. Procedure: Initial setup 1. Create a fork of [pingcap-docsite-preview](https://github.com/Oreoxmt/pingcap-docsite-preview). Make sure that you have enabled GitHub Actions for your fork. : ![Enable GitHub Actions for your repository](images/enable_gha.png) 2. Connect your fork to a cloud service. This document uses [Vercel](https://vercel.com) as an example: 1. Log in to [Vercel](https://vercel.com). 2. In the Overview page, click Add New... > Project. 3. In the Import Git Repository page, search for your (`pingcap-docsite-preview`) and click Import. 4. In the Configure Project page, fill in the following information: * Root Directory: leave it as `./` * Build and Output Settings > Build Command: `./build.sh` * Build and Output Settings > Output Directory: `website-docs/public` * Environment Variables: add a variable with the name `ENABLE_EXPERIMENTAL_COREPACK` and the value `1`. For more information, see [Configuring a Build: Corepack](https://vercel.com/docs/builds/configure-a-build#corepack). 5. Click Deploy. 6. After approximately 5 minutes, the website is deployed. You can get the preview URL from your Vercel project page. For more information, refer to [Deploy the preview website](deploy-docsite.html). Procedure: Steps 1. Optional: Manually trigger the [sync_scaffold.yml](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/main/.github/workflows/sync_scaffold.yml) workflow for the `main` branch of your . 2. In your fork, create a new branch `multi-pr-preview` from the `main` branch. 3. Update the configuration in [sync_mult_prs.sh](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/main/sync_mult_prs.sh). 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: ```SHELL ./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 ``` Note: `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](https://docs.github.com/en/get-started/quickstart/github-glossary#base-branch). Note: For TiDB and TiDB Operator, certain document sections (such as `ai`, `develop`, `best-practices`, `api`, and `releases` for TiDB; `releases` for TiDB Operator) are rendered from a fixed canonical branch by the top navigation, regardless of the pull request's base branch. When the base branch differs from the canonical branch, the [sync_pr.sh](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/main/sync_pr.sh) script automatically syncs changed files in those sections to the canonical branch path as well, so they appear correctly in the preview. Note: When the base branch is a localization branch in the form `i18n-{locale}-{master|release-*}` (for example, `i18n-ja-release-8.5`), the [sync_pr.sh](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/main/sync_pr.sh) script normalizes the destination to `markdown-pages/{locale}/{product}/{master|release-*}` so the preview renders at its canonical localized path. For example, a PR with base branch `i18n-ja-release-8.5` on `pingcap/docs` is synced to `markdown-pages/ja/tidb/release-8.5` instead of `markdown-pages/en/tidb/i18n-ja-release-8.5`. To preview in a different version, such as v1.0, when the base branch of these pull requests is `master`, configure as follows: ```SHELL 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/ ``` For more information, see [Automatically update from multiple PRs](update-content.html#update-from-multiple-pull-requests). 4. Manually trigger the [sync_mult_prs.yml](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/main/.github/workflows/sync_mult_prs.yml) workflow for `multi-pr-preview` branch. You can view the website deployment status in the [Deployments](https://vercel.com/docs/projects/project-dashboard#deployments) page of your Vercel project. 5. Optional: To maintain continuous synchronization with these PRs, you can [periodically update](update-content.html#perform-periodic-updates) the content using GitHub Actions. For example, to update `multi-pr-preview` branch every 1 hour, configure the [sync_scheduler.yml](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/main/.github/workflows/sync_scheduler.yml) workflow in your default branch as follows: ```YAML name: Sync docs on schedule on: schedule: - cron: "0 */1 * * *" # every 1 hour 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_mult_prs.yml --ref multi-pr-preview ``` # Usage Guide Procedure: Steps to preview document changes 1. Fork the [pingcap-docsite-preview](https://github.com/Oreoxmt/pingcap-docsite-preview) repository. 2. Update the scaffold of [PingCAP documentation website](https://docs.pingcap.com), including version selection, table of contents, index pages, and the homepage. For more information, see [Update scaffold](update-scaffold.html). 3. Update the documentation content you want to preview. For more information, see [Update content](update-content.html). 4. Deploy the preview website either locally or on a static hosting service. For more information, see [Deploy your website](deploy-docsite.html). Procedure: Notes * Fork [pingcap-docsite-preview](https://github.com/Oreoxmt/pingcap-docsite-preview) to your GitHub account first. * Ensure your remains synchronized with the upstream repository. * Avoid updating the `main` branch of your fork. This helps prevent conflicts with the upstream repository. # Step 1. Update scaffold This document introduces what the scaffold is and how to update it. Procedure: Concept Procedure: An example of the scaffold Procedure: Update the scaffold in GitHub Actions * In your , the [sync_scaffold.yml](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/main/.github/workflows/sync_scaffold.yml) workflow can be manually triggered (`workflow_dispatch`) or automatically triggered every 15 days (`0 0 */15 * *`) by default. ```YAML 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](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/main/.github/workflows/sync_scaffold.yml) file. For more information, see [Events that trigger workflows](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows). Procedure: Update the scaffold locally * To update the scaffold of your on your local machine, you can execute the [sync_scaffold.sh](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/main/sync_scaffold.sh) script. This script automatically updates the scaffold to the latest version from [pingcap/docs-staging](https://github.com/pingcap/docs-staging). * To update the scaffold to a specific version, you can specify a branch or commit in [sync_scaffold.sh](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/main/sync_scaffold.sh). * Examples: Update to the latest version: ```SHELL git clone https://github.com/Oreoxmt/pingcap-docsite-preview.git cd pingcap-docsite-preview ./sync_scaffold.sh ``` Update to a specific branch: ```SHELL git clone https://github.com/Oreoxmt/pingcap-docsite-preview.git cd pingcap-docsite-preview ./sync_scaffold.sh $BRANCH ``` Update to a specific commit: ```SHELL git clone https://github.com/Oreoxmt/pingcap-docsite-preview.git cd pingcap-docsite-preview ./sync_scaffold.sh $COMMIT ``` # Step 2. Update content In the [pingcap-docsite-preview](https://github.com/Oreoxmt/pingcap-docsite-preview) context, content refers to all documents on [PingCAP documentation website](https://docs.pingcap.com). You can update content in the following ways: * [Automatically update from a pull request](#update-from-a-pull-request) * [Automatically update from multiple pull requests](#update-from-multiple-pull-requests) * [Manually update](#perform-a-manual-update) To maintain continuous synchronization with pull requests, you can schedule [periodic updates](#perform-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. GitHub Actions: Make sure that you have enabled GitHub Actions for your fork. : ![Enable GitHub Actions for your repository](images/enable_gha.png) 1. Create a pull request to one of the following repositories: * [pingcap/docs](https://github.com/pingcap/docs) * [pingcap/docs-cn](https://github.com/pingcap/docs-cn) * [pingcap/docs-tidb-operator](https://github.com/pingcap/docs-tidb-operator) 2. In your , create a new branch from the `main` branch following these naming conventions: By documentation: | Documentation |Branch naming convention | ------------------------------------------- | [TiDB (English)](https://docs.pingcap.com/tidb/stable) |`preview/pingcap/docs/{PR_NUMBER}` | | [TiDB (Chinese)](https://docs.pingcap.com/zh/tidb/stable) |`preview/pingcap/docs-cn/{PR_NUMBER}` | | [TiDB Cloud](https://docs.pingcap.com/tidbcloud) |`preview-cloud/pingcap/docs/{PR_NUMBER}` | | [TiDB Operator](https://docs.pingcap.com/tidb-in-kubernetes/stable) |`preview-operator/pingcap/docs-tidb-operator/{PR_NUMBER}` | By repository: ```PLANTUML @startmindmap scale 0.75 * pingcap/ ** docs *** TiDB **** preview/pingcap/docs/{PR_NUMBER} ***: TiDB Cloud; **** preview-cloud/pingcap/docs/{PR_NUMBER} ** docs-cn *** preview/pingcap/docs-cn/{PR_NUMBER} ** docs-tidb-operator *** preview-operator/pingcap/docs-tidb-operator/{PR_NUMBER} @endmindmap ``` 3. The [sync_pr.yml](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/main/.github/workflows/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](#perform-periodic-updates). 4. To deploy your changes to a preview website, see [Deploy the preview website](deploy-docsite.html). Local machine: Procedure: Prerequisites * Install [jq](https://jqlang.github.io/jq/download/). * Generate a [GitHub personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) with the repo scope and set it as the `GITHUB_TOKEN` environment variable value. 1. Create a pull request to one of the following repositories: * [pingcap/docs](https://github.com/pingcap/docs) * [pingcap/docs-cn](https://github.com/pingcap/docs-cn) * [pingcap/docs-tidb-operator](https://github.com/pingcap/docs-tidb-operator) 2. In your , create a new branch from the `main` branch following these naming conventions: By documentation: | Documentation |Branch naming convention | ------------------------------------------- | [TiDB (English)](https://docs.pingcap.com/tidb/stable) |`preview/pingcap/docs/{PR_NUMBER}` | | [TiDB (Chinese)](https://docs.pingcap.com/zh/tidb/stable) |`preview/pingcap/docs-cn/{PR_NUMBER}` | | [TiDB Cloud](https://docs.pingcap.com/tidbcloud) |`preview-cloud/pingcap/docs/{PR_NUMBER}` | | [TiDB Operator](https://docs.pingcap.com/tidb-in-kubernetes/stable) |`preview-operator/pingcap/docs-tidb-operator/{PR_NUMBER}` | By repository: ```PLANTUML @startmindmap scale 0.75 * pingcap/ ** docs *** TiDB **** preview/pingcap/docs/{PR_NUMBER} ***: TiDB Cloud; **** preview-cloud/pingcap/docs/{PR_NUMBER} ** docs-cn *** preview/pingcap/docs-cn/{PR_NUMBER} ** docs-tidb-operator *** preview-operator/pingcap/docs-tidb-operator/{PR_NUMBER} @endmindmap ``` ```SHELL git clone https://github.com/Oreoxmt/pingcap-docsite-preview.git cd pingcap-docsite-preview git checkout -b preview/pingcap/docs/{PR_NUMBER} ``` 3. Execute the [sync_pr.sh](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/main/sync_pr.sh) script to update the content from the pull request. ```SHELL ./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](deploy-docsite.html). ## Update from multiple pull requests You can automatically update the preview content from multiple pull requests by creating a new branch and configuring it. GitHub Actions: Make sure that you have enabled GitHub Actions for your fork. : ![Enable GitHub Actions for your repository](images/enable_gha.png) 1. Create pull requests to the following repositories: * [pingcap/docs](https://github.com/pingcap/docs) * [pingcap/docs-cn](https://github.com/pingcap/docs-cn) * [pingcap/docs-tidb-operator](https://github.com/pingcap/docs-tidb-operator) 2. In your , create a new branch from the `main` branch. Do not include a `preview` prefix in the branch name. 3. Update the configuration in the [sync_mult_prs.sh](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/main/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: ```SHELL ./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 ``` Note: `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](https://docs.github.com/en/get-started/quickstart/github-glossary#base-branch). Note: For TiDB and TiDB Operator, certain document sections (such as `ai`, `develop`, `best-practices`, `api`, and `releases` for TiDB; `releases` for TiDB Operator) are rendered from a fixed canonical branch by the top navigation, regardless of the pull request's base branch. When the base branch differs from the canonical branch, the [sync_pr.sh](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/main/sync_pr.sh) script automatically syncs changed files in those sections to the canonical branch path as well, so they appear correctly in the preview. Note: When the base branch is a localization branch in the form `i18n-{locale}-{master|release-*}` (for example, `i18n-ja-release-8.5`), the [sync_pr.sh](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/main/sync_pr.sh) script normalizes the destination to `markdown-pages/{locale}/{product}/{master|release-*}` so the preview renders at its canonical localized path. For example, a PR with base branch `i18n-ja-release-8.5` on `pingcap/docs` is synced to `markdown-pages/ja/tidb/release-8.5` instead of `markdown-pages/en/tidb/i18n-ja-release-8.5`. To preview in a different version, such as v1.0, when the base branch of these pull requests is `master`, configure as follows: ```SHELL 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/ ``` 4. Manually trigger the [sync_mult_prs.yml](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/main/.github/workflows/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](#perform-periodic-updates). 5. To deploy your changes to a preview website, see [Deploy the preview website](deploy-docsite.html). Local machine: Procedure: Prerequisites * Install [jq](https://jqlang.github.io/jq/download/). * Generate a [GitHub personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) with the repo scope and set it as the `GITHUB_TOKEN` environment variable value. 1. Create pull requests to the following repositories: * [pingcap/docs](https://github.com/pingcap/docs) * [pingcap/docs-cn](https://github.com/pingcap/docs-cn) * [pingcap/docs-tidb-operator](https://github.com/pingcap/docs-tidb-operator) 2. In your , create a new branch from the `main` branch. Do not include a `preview` prefix in the branch name. ```SHELL git clone https://github.com/Oreoxmt/pingcap-docsite-preview.git cd pingcap-docsite-preview git checkout -b multi-pr-preview ``` 3. Update the configuration in the [sync_mult_prs.sh](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/main/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: ```SHELL ./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 ``` Note: `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](https://docs.github.com/en/get-started/quickstart/github-glossary#base-branch). Note: For TiDB and TiDB Operator, certain document sections (such as `ai`, `develop`, `best-practices`, `api`, and `releases` for TiDB; `releases` for TiDB Operator) are rendered from a fixed canonical branch by the top navigation, regardless of the pull request's base branch. When the base branch differs from the canonical branch, the [sync_pr.sh](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/main/sync_pr.sh) script automatically syncs changed files in those sections to the canonical branch path as well, so they appear correctly in the preview. Note: When the base branch is a localization branch in the form `i18n-{locale}-{master|release-*}` (for example, `i18n-ja-release-8.5`), the [sync_pr.sh](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/main/sync_pr.sh) script normalizes the destination to `markdown-pages/{locale}/{product}/{master|release-*}` so the preview renders at its canonical localized path. For example, a PR with base branch `i18n-ja-release-8.5` on `pingcap/docs` is synced to `markdown-pages/ja/tidb/release-8.5` instead of `markdown-pages/en/tidb/i18n-ja-release-8.5`. To preview in a different version, such as v1.0, when the base branch of these pull requests is `master`, configure as follows: ```SHELL 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/ ``` 4. Execute the [sync_mult_prs.sh](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/main/sync_mult_prs.sh) script to update the content from these pull requests. ```SHELL ./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](#perform-periodic-updates). 5. To deploy your changes to a preview website, see [Deploy the preview website](deploy-docsite.html). ## Perform periodic updates You can use the [sync_scheduler.yml](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/main/.github/workflows/sync_scheduler.yml) [GitHub workflow](https://docs.github.com/en/actions/using-workflows/about-workflows) 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. : ![Enable GitHub Actions for your repository](images/enable_gha.png) 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](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/main/.github/workflows/sync_scheduler.yml) workflow in your default branch as follows: ```YAML 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](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onschedule). ## Perform a manual update 1. Clone your , change to the directory, and create a new branch: ```SHELL git clone https://github.com/Oreoxmt/pingcap-docsite-preview.git cd pingcap-docsite-preview git checkout -b test-manual-update ``` 2. Optional: [Update the scaffold](update-scaffold.html): ```SHELL ./sync_scaffold.sh [BRANCH|COMMIT] ``` 3. Place the files you want to preview under the `markdown-pages` directory according to the following structure: ```SHELL_SESSION . ├── 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 ``` Note: It is recommended to keep the original folder structure, so you can replace `docs.pingcap.com` with [http://localhost:8000/](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`. 4. 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](deploy-docsite.html). # Step 3. Deploy your website Procedure: Methods for deployment * Deploy your website using a cloud service, such as [Vercel](https://vercel.com), [Cloudflare Pages](https://dash.cloudflare.com), and [Netlify](https://app.netlify.com): * [Deploy your website using Vercel](deploy-vercel.html) * [Deploy your website using Cloudflare Pages](deploy-cloudflare-pages.html) * [Deploy your website using Netlify](deploy-netlify.html) * Deploy your website locally on your machine: * [Deploy your website locally](deploy-local.html) Procedure: Comparison of different methods # Deploy your website using Vercel This document describes how to deploy your documentation website using Vercel. Procedure: Steps Procedure: Note # Deploy your website using Cloudflare Pages This document describes how to deploy your documentation website using Cloudflare Pages. Note: This deployment method is only available for Cloudflare Pages [v2 build system](https://blog.cloudflare.com/moderizing-cloudflare-pages-builds-toolbox/). Procedure: Steps Procedure: Note # Deploy your website using Netlify This document describes how to deploy your documentation website using Netlify. Procedure: Steps Procedure: Note # Deploy your website locally This document describes how to deploy your documentation website using your local machine. Procedure: Prerequisites Procedure: Steps 1. Clone the `pingcap-docsite-preview` to your local machine and switch to the branch you want to preview. ```SHELL git clone https://github.com/Oreoxmt/pingcap-docsite-preview.git cd pingcap-docsite-preview git checkout preview/pingcap/docs/1234 ``` 2. Run the following command to preview the current branch locally. ```SHELL ./build.sh dev ``` Note: During the first deployment, [build.sh](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/main/build.sh) fetches and caches the latest static site generator of PingCAP documentation website ([pingcap/website-docs](https://github.com/pingcap/website-docs)). To update to the latest website generator, you need to remove the existing `website-docs` folder before running `./build.sh dev`. 3. Optional: Preview images. During the build process, the `website-docs/public` directory is generated. To preview images in development mode, copy the image folders to `website-docs/public/media/{lang}/{product}/`. For example: ```SHELL mkdir -p website-docs/public/media/en/tidb cp -r markdown-pages/en/tidb/master/media/. website-docs/public/media/en/tidb/ mkdir -p website-docs/public/media/zh/tidb cp -r markdown-pages/zh/tidb/master/media/. website-docs/public/media/zh/tidb/ mkdir -p website-docs/public/media/en/tidb-in-kubernetes cp -r markdown-pages/en/tidb-in-kubernetes/master/media/. website-docs/public/media/en/tidb-in-kubernetes/ mkdir -p website-docs/public/media/zh/tidb-in-kubernetes cp -r markdown-pages/zh/tidb-in-kubernetes/master/media/. website-docs/public/media/zh/tidb-in-kubernetes/ mkdir -p website-docs/public/media/en/tidb-cloud cp -r markdown-pages/en/tidb-cloud/master/media/. website-docs/public/media/en/tidb-cloud/ ``` Note: When running `./build.sh` (production build), images are copied automatically. Manual copying is only needed when using development mode (`./build.sh dev`). 4. Open the preview URL in your browser. For example, [http://localhost:8000](http://localhost:8000). Note that if port `8000` is not available, you need to type `y` in your terminal to use another port: ```SHELL_SESSION Something is already running at port 8000 ✔ Would you like to run the app at another port instead? … yes ... You can now view website-docs in the browser. http://localhost:8001/ ``` # Advanced Usage ## Automatically prune merged preview branches To keep your fork clean, you can automatically prune merged preview branches using [prune_branches.yml](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/main/.github/workflows/prune_branches.yml) or [prune_preview_branches.sh](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/main/prune_preview_branches.sh). GitHub Actions: Make sure that you have enabled GitHub Actions for your fork. : ![Enable GitHub Actions for your repository](images/enable_gha.png) In your fork, manually trigger the [prune_branches.yml](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/main/.github/workflows/prune_branches.yml) workflow for the `main` branch. After the workflow runs, merged preview branches will be deleted from the remote repository. Local machine: Procedure: Prerequisites * Install [jq](https://jqlang.github.io/jq/download/). * Generate a [GitHub personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) with the repo scope and set it as the `GITHUB_TOKEN` environment variable value. Execute the [prune_preview_branches.sh](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/main/prune_preview_branches.sh) script in your fork. * To prune locally merged preview branches: ```SHELL export DELETE_BRANCHES="local" ./prune_preview_branches.sh ``` * To prune branches in the remote repository: ```SHELL export DELETE_BRANCHES="remote" ./prune_preview_branches.sh ``` ## Customize the documentation website frontend You can customize the appearance of the documentation by modifying the frontend branch or repository settings. By default, [pingcap-docsite-preview](https://github.com/Oreoxmt/pingcap-docsite-preview) uses the `master` branch of the [website-docs](https://github.com/pingcap/website-docs) repository for the frontend. To use a different branch or repository: 1. Open the [build.sh](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/main/build.sh) script. 2. In the script, locate and modify the following line ([L55](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/4634a77e072b29aa793614d8209c08ae79df73ce/build.sh#L55)): ```BASH git clone --single-branch --branch master https://github.com/pingcap/website-docs ``` Replace `master` with the name of your desired branch, or update the repository URL `https://github.com/pingcap/website-docs` to your preferred repository. 3. Preview your changes by updating the scaffold and content. For more information, see [Usage Guide](usage-guide.html). # Release Notes ## v1.4 (preview scope and experience) In v1.4.x, [pingcap-docsite-preview](https://github.com/Oreoxmt/pingcap-docsite-preview) expands preview scopes to new workflows and refines the preview experience. ### v1.4.0 Release date: May 20, 2026 * Support automatically routing preview content when the pull request's base branch is a localization (i18n) branch in the form `i18n-{locale}-{master|release-*}`. The [sync_pr.sh](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/v1.4.0/sync_pr.sh) script normalizes the destination to `markdown-pages/{locale}/{product}/{master|release-*}` so the preview renders at its canonical localized path. For example, a PR with base branch `i18n-ja-release-8.5` on `pingcap/docs` is synced to `markdown-pages/ja/tidb/release-8.5`. For more information, see [Update from a pull request](update-content.html#update-from-a-pull-request). * Switch `pnpm install` to `--frozen-lockfile` in the [build.sh](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/v1.4.0/build.sh) script so that the build fails fast when `pnpm-lock.yaml` is out of sync with `package.json`, ensuring reproducible builds. ([#48](https://github.com/Oreoxmt/pingcap-docsite-preview/pull/48)) ## v1.3 (website compatibility) In v1.3.x, rendering is consistent for new features introduced from 2025 through May 2026 for [PingCAP documentation website](https://docs.pingcap.com). ### v1.3.5 Release date: March 27, 2026 * Support syncing changed files in TOC namespace folders to the canonical branch path when the pull request's base branch differs from the canonical branch used by the top navigation introduced in [pingcap/website-docs#683](https://github.com/pingcap/website-docs/pull/683). For more information, see [Update from multiple pull requests](update-content.html#update-from-multiple-pull-requests). ### v1.3.4 Release date: March 26, 2026 * Support syncing [tooltip-terms.json](https://github.com/pingcap/docs-staging/blob/main/tooltip-terms.json) as part of the scaffold when you run the [sync_scaffold.sh](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/v1.3.4/sync_scaffold.sh) script. This file is synced only if it exists in the source repository. ### v1.3.3 Release date: March 25, 2026 * Support compatibility with [pingcap/website-docs#686](https://github.com/pingcap/website-docs/pull/686), which uses pnpm as the package manager. Note: If you deploy using Vercel, add the environment variable `ENABLE_EXPERIMENTAL_COREPACK` with the value `1` to your Vercel project to enable Corepack support. For more information, see [Deploy your website using Vercel](deploy-vercel.html). ### v1.3.2 Release date: September 5, 2025 * Support replacing variables with actual values before a preview deployment. * (Internal) Fix the test utility to handle dependencies correctly. * (Internal) Refactor the `commit_changes()` function in `sync_pr.sh` and `sync_mult_prs.sh` to support custom and multiple Git commit operations. * (Internal) Update unit test cases to match the changes introduced in this release. ### v1.3.1 Release date: September 3, 2025 * (Internal) Fix the issue that the [run_tests.yml](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/v1.3.0/.github/workflows/run_tests.yml) workflow does not report an error when unit tests fail. * (Internal) Update the unit test case for "Sync scaffold from a commit" to match the change introduced in v1.3.0. ### v1.3.0 Release date: August 26, 2025 * Support syncing `TOC-*.md` files, such as `TOC-tidb-cloud-starter.md` and `TOC-tidb-cloud-essential.md`, when you run the [sync_scaffold.sh](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/v1.3.0/sync_scaffold.sh) script. This update fixes preview failures on sites with multiple tables of contents (TOCs) and improves compatibility with the multi-TOC feature in [PingCAP documentation website](https://docs.pingcap.com). ## v1.2 (advanced usage) In v1.2.x, you can use some advanced features to streamline your usage. ### v1.2.0 Release date: July 11, 2024 * Support pruning merged preview branches using [prune_branches.yml](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/main/.github/workflows/prune_branches.yml) or [prune_preview_branches.sh](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/main/prune_preview_branches.sh). Procedure: Usage ## v1.1 (scheduler management) In v1.1.x, you can use [pingcap-docsite-preview](https://github.com/Oreoxmt/pingcap-docsite-preview) to manage preview schedules. ### v1.1.0 Release date: December 6, 2023 * Support maintaining continuous synchronization with pull requests using the [sync_scheduler.yml](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/v1.1.0/.github/workflows/sync_scheduler.yml) workflow in [GitHub Actions](https://docs.github.com/en/actions). (close [#32](https://github.com/Oreoxmt/pingcap-docsite-preview/issues/32)) Procedure: Usage ## v1.0 (consistent rendering) In v1.0.x, you can use [pingcap-docsite-preview](https://github.com/Oreoxmt/pingcap-docsite-preview) to preview documents with rendering that matches the [PingCAP documentation website](https://docs.pingcap.com). ### v1.0.0 Release date: December 5, 2023 * Enhance the document rendering to maintain consistency with the [PingCAP documentation website](https://docs.pingcap.com) by removing all `{{< copyable "..." >}}` strings in Markdown files. (close [#30](https://github.com/Oreoxmt/pingcap-docsite-preview/issues/30)) ## v0.4 (deployment) In v0.4.x, you can use [pingcap-docsite-preview](https://github.com/Oreoxmt/pingcap-docsite-preview) to build the documentation website for preview. ### v0.4.0 Release date: December 5, 2023 * Support deploying the documentation website using the [build.sh](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/v0.4.0/build.sh) script. Procedure: Methods for deployment 1. Deploy your website using a cloud service, such as [Vercel](https://vercel.com), [Cloudflare Pages](https://dash.cloudflare.com), and [Netlify](https://app.netlify.com): * [Deploy your website using Vercel](deploy-vercel.html) * [Deploy your website using Cloudflare Pages](deploy-cloudflare-pages.html) * [Deploy your website using Netlify](deploy-netlify.html) 2. Deploy your website locally on your machine: * [Deploy your website locally](deploy-local.html) ## v0.3 (multiple pull requests preview) In v0.3.x, you can use [pingcap-docsite-preview](https://github.com/Oreoxmt/pingcap-docsite-preview) to update the documents from multiple pull requests. This feature applies to pull requests from the following repositories: * [pingcap/docs](https://github.com/pingcap/docs) * [pingcap/docs-cn](https://github.com/pingcap/docs-cn) * [pingcap/docs-tidb-operator](https://github.com/pingcap/docs-tidb-operator) ### v0.3.2 Release date: December 4, 2023 * (Internal) Support running unit tests using the [run_tests.yml](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/v0.3.2/.github/workflows/run_tests.yml) workflow in [GitHub Actions](https://docs.github.com/en/actions). (close [#26](https://github.com/Oreoxmt/pingcap-docsite-preview/issues/26)) ### v0.3.1 Release date: December 4, 2023 * (Internal) Support concurrently executing tests using the [test/test.py](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/v0.3.1/test/test.py) script. (close [#24](https://github.com/Oreoxmt/pingcap-docsite-preview/issues/24)) ### v0.3.0 Release date: December 4, 2023 * Support synchronizing documents from multiple pull requests using the [sync_mult_prs.sh](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/v0.3.0/sync_mult_prs.sh) script or the [sync_mult_prs.yml](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/v0.3.0/.github/workflows/sync_mult_prs.yml) workflow in [GitHub Actions](https://docs.github.com/en/actions). (close [#18](https://github.com/Oreoxmt/pingcap-docsite-preview/issues/18)) Procedure: Usage ## v0.2 (single pull request preview) In v0.2.x, you can use [pingcap-docsite-preview](https://github.com/Oreoxmt/pingcap-docsite-preview) to update the documents from a pull request. This feature applies to pull requests from the following repositories: * [pingcap/docs](https://github.com/pingcap/docs) * [pingcap/docs-cn](https://github.com/pingcap/docs-cn) * [pingcap/docs-tidb-operator](https://github.com/pingcap/docs-tidb-operator) ### v0.2.2 Release date: November 29, 2023 * Fix the issue that [sync_pr.sh](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/v0.2.2/sync_pr.sh) fails to work when the `TEST` environment variable is unset. (close [#21](https://github.com/Oreoxmt/pingcap-docsite-preview/issues/21)) ### v0.2.1 Release date: November 29, 2023 * Support synchronizing documents from a pull request using the [sync_pr.yml](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/v0.2.1/.github/workflows/sync_pr.yml) workflow in [GitHub Actions](https://docs.github.com/en/actions). (close [#19](https://github.com/Oreoxmt/pingcap-docsite-preview/issues/19)) Procedure: Usage ### v0.2.0 Release date: September 21, 2023 * Support synchronizing documents from a pull request using [sync_pr.sh](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/v0.2.0/sync_pr.sh). (close [#16](https://github.com/Oreoxmt/pingcap-docsite-preview/issues/16)) Procedure: Usage ## v0.1 (scaffold synchronization) In v0.1.x, you can use [pingcap-docsite-preview](https://github.com/Oreoxmt/pingcap-docsite-preview) to synchronize the scaffold from [pingcap/docs-staging](https://github.com/pingcap/docs-staging). ### v0.1.7 Release date: September 21, 2023 * (Internal) Refactor the test framework to support testing shell scripts using a configuration file [test_config.toml](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/v0.1.7/test_config.toml). (close [#12](https://github.com/Oreoxmt/pingcap-docsite-preview/issues/12)) Procedure: Usage 1. Define the test configuration in [test_config.toml](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/v0.1.7/test_config.toml). For example, to test the [sync_scaffold.sh](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/v0.1.7/sync_scaffold.sh) script, configure as follows: ```YAML [sync_scaffold] diff_command = "diff -qrs data actual --exclude temp --exclude '*.log' --exclude sync_scaffold.sh" test_target = "sync_scaffold.sh" [[sync_scaffold.test_cases]] name = "Sync scaffold from a commit" args = "265874160aec258f9c725b0e940bc803ca558bda" directory = "test/sync_scaffold/" ``` 2. Run the test using `python3 test/test.py`: ```SHELL_SESSION $ python3 test/test.py Running Tests... 100%|█████████████████████████████████████████████████████████████████████████████| 1/1 [00:18<00:00, 18.78s/it] --------------------------------------------------Test Results-------------------------------------------------- ✅ Test Sync scaffold from a commit passed successfully Tests passed: 1 of 1 18.80s ---------------------------------------------------------------------------------------------------------------- ``` ### v0.1.6 Release date: September 1, 2023 * Fix the issue that the "failed to push some refs" error is reported in GitHub Actions when multiple workflows are queued. This issue is fixed by adding `concurrency` and introducing a new [git_push.sh](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/v0.1.6/.github/git_push.sh) script. (close [#13](https://github.com/Oreoxmt/pingcap-docsite-preview/issues/13)) ### v0.1.5 Release date: August 21, 2023 * Support synchronizing the scaffold from a specified branch or a commit to ensure the test repeatability. (close [#5](https://github.com/Oreoxmt/pingcap-docsite-preview/issues/5)) Procedure: Usage ### v0.1.4 Release date: August 21, 2023 * Introduce the `TEST` environment variable to control whether to ignore the `git commit` command in the [sync_scaffold.sh](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/v0.1.4/sync_scaffold.sh) script. This enhancement aims to avoid unnecessary commits during test script execution. (close [#6](https://github.com/Oreoxmt/pingcap-docsite-preview/issues/6)) * (Internal) Support setting environment variables in the test framework [test_util.py](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/v0.1.4/test/test_util.py). (close [#7](https://github.com/Oreoxmt/pingcap-docsite-preview/issues/7)) * Exclude empty directories when executing [sync_scaffold.sh](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/v0.1.4/sync_scaffold.sh) using the `rsync --prune-empty-dirs` option. (close [#8](https://github.com/Oreoxmt/pingcap-docsite-preview/issues/8)) ### v0.1.3 Release date: July 2, 2023 * Fix the "fatal: not in a git directory" error that occurs when executing the `git config user.name` command during step 4 of the [sync_scaffold.yml](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/v0.1.3/.github/workflows/sync_scaffold.yml) workflow. (fixed by [#3](https://github.com/Oreoxmt/pingcap-docsite-preview/pull/3)) * Fix the issue that the `git add .` command exits with an error "The following paths are ignored by one of your .gitignore files". This command is now modified to `git add . || true`, allowing it to continue even if it encounters ignored files. This effectively bypasses the error and prevents the command from terminating unexpectedly. (fixed by [#4](https://github.com/Oreoxmt/pingcap-docsite-preview/pull/4)) ### v0.1.2 Release date: July 2, 2023 * Support synchronizing the scaffold using the [sync_scaffold.yml](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/v0.1.2/.github/workflows/sync_scaffold.yml) workflow in [GitHub Actions](https://docs.github.com/en/actions). Procedure: Usage ### v0.1.1 Release date: July 2, 2023 * (Internal) Introduce a test framework [test_util.py](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/v0.1.1/test/test_util.py) to enhance the reliability and efficiency of [pingcap-docsite-preview](https://github.com/Oreoxmt/pingcap-docsite-preview). Procedure: Key features * `DocSitePreviewTest._setup_test_env()`: clean up the test environment, copy the target script to the test environment, and ensure that the script can be executed. * `DocSitePreviewTest.execute()`: execute the target script in the test environment and save the output in the `test/.../actual` directory. * `DocSitePreviewTest.verify()`: compare the actual output (`test/.../actual`) with the expected output (`test/.../data`). * Add a specific test for the [sync_scaffold.sh](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/v0.1.1/sync_scaffold.sh) script: * Expected output: [test/sync_scaffold/data/](https://github.com/Oreoxmt/pingcap-docsite-preview/tree/v0.1.1/test/sync_scaffold/data) * Test program: [test/sync_scaffold/test_sync_scaffold.py](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/v0.1.1/test/sync_scaffold/test_sync_scaffold.py) ### v0.1.0 Release date: July 2, 2023 * Support synchronizing the scaffold with the latest version of [pingcap/docs-staging](https://github.com/pingcap/docs-staging) using the [sync_scaffold.sh](https://github.com/Oreoxmt/pingcap-docsite-preview/blob/v0.1.0/sync_scaffold.sh) script. Procedure: Concept Procedure: Usage