Usage Scenarios

Initial setup

1. Make sure that you have installed the following tools:

   • Node.js 16 or later

   • Yarn 1

   • Git

2. Create a fork of pingcap-docsite-preview.

3. Clone the fork to your local machine.

   git clone https://github.com/Oreoxmt/pingcap-docsite-preview.git

Steps

Perform the following steps to preview changes locally.

1. Change to your fork directory and create a new branch.

   cd pingcap-docsite-preview git checkout -b test-manual-update

2. Optional: Update the scaffold to the latest version if needed.

   ./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, add the file markdown-pages/en/tidb/master/overview.md.

   For more information, see Perform a manual update.

4. Run the following command to preview your changes locally.

   ./build.sh dev

5. Open the preview URL in your browser. For example, http://localhost:8000.

   For more information, see Deploy the documentation website locally.

Initial setup

1. Create a fork of pingcap-docsite-preview.

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

   

2. Connect your fork to a cloud service. This document uses Vercel as an example:

   1. Log in to Vercel.

   2. In the Overview page, click Add New... > Project.

   3. In the Import Git Repository page, search for your fork (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

   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.

Steps

The following steps show you how to preview document changes in https://github.com/pingcap/docs/pull/1234 to TiDB documentation.

1. Optional: Manually trigger the sync_scaffold.yml workflow for the main branch of your fork.

2. In your fork, create a new branch preview/pingcap/docs/1234 from the main branch.

3. The sync_pr.yml workflow is automatically triggered.

   You can view the website deployment status in the Deployments page of your Vercel project.

4. Optional: To maintain continuous synchronization with this PR, you can periodically update the content using GitHub Actions. For example, to update preview/pingcap/docs/1234 branch every 1 hour, 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 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

Initial setup

1. Create a fork of pingcap-docsite-preview.

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

   

2. Connect your fork to a cloud service. This document uses Vercel as an example:

   1. Log in to Vercel.

   2. In the Overview page, click Add New... > Project.

   3. In the Import Git Repository page, search for your fork (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

   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.

Steps

The following steps show you how to preview document changes in multiple PRs.

1. Optional: Manually trigger the sync_scaffold.yml workflow for the main branch of your fork.

2. In your fork, create a new branch multi-pr-preview from the main branch.

3. Update the configuration in 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:

   ./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

   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/

   For more information, see Automatically update from multiple PRs.

4. Manually trigger the sync_mult_prs.yml workflow for multi-pr-preview branch.

   You can view the website deployment status in the Deployments page of your Vercel project.

5. Optional: To maintain continuous synchronization with these PRs, you can periodically update the content using GitHub Actions. For example, to update multi-pr-preview branch every 1 hour, 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 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