qiancai / pingcap-docsite-preview

A preview environment to review changes to PingCAP documentation website before merging pull requests.

Overview

pingcap-docsite-preview is a tool designed for previewing changes to PingCAP documentation website 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.

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.

Scope

pingcap-docsite-preview supports previewing documentation for TiDB, TiDB Cloud, and TiDB Operator. You can preview PRs from the following repositories:

• pingcap/docs
• pingcap/docs-cn
• pingcap/docs-tidb-operator

Usage scenarios

• Preview and validate minor changes in 2 minutes.
• Preview a PR and collaborate with reviewers.
• Preview multiple PRs across different repositories.

Steps to preview document changes

@startuml

hide empty description
[*] --> fork
fork --> UpdateScaffold
state "update scaffold" as UpdateScaffold {
state "Terminal" as UpdateScaffoldScript
UpdateScaffoldScript: sync_scaffold.sh\n\n
state "GitHub Actions" as UpdateScaffoldGHA
UpdateScaffoldGHA: sync_scaffold.yml\n\n

}
UpdateScaffold -right-> UpdateContent
state "update content" as UpdateContent {
state "from a PR" as PR
state "from multi PRs" as PRs
state manual
PR: sync_pr.sh\n
PR: sync_pr.yml
PRs: sync_mult_prs.sh\n
PRs: sync_mult_prs.yml
manual: markdown-pages\n\n

}
state "periodic update" as PeriodicUpdate{
PeriodicUpdate: GitHub Actions\n\nsync_scheduler.yml
}
PeriodicUpdate -[dashed]-> UpdateContent
state "deploy website" as DeployWebsite {
state local
local: ./build.sh dev\n\n
state cloud
cloud: Netlify
cloud: Vercel
cloud: Cloudflare Pages
}
UpdateContent --> DeployWebsite
@enduml

To preview document changes, perform the following steps:

1. Fork the pingcap-docsite-preview repository.

2. Update the scaffold of PingCAP documentation website, including version selection, table of contents, index pages, and the homepage.

   For more information, see Update scaffold.

3. Update the documentation content you want to preview.

   For more information, see Update content.

4. Deploy the preview website either locally or on a static hosting service.

   For more information, see Deploy your website.