Skip to content

docs(guide): rewrite SSG documentation with comprehensive explanations#2985

Merged
SoonIter merged 7 commits intomainfrom
syt-vibe-kanban/b5eb-guide-basic-ssg
Jan 9, 2026
Merged

docs(guide): rewrite SSG documentation with comprehensive explanations#2985
SoonIter merged 7 commits intomainfrom
syt-vibe-kanban/b5eb-guide-basic-ssg

Conversation

@SoonIter
Copy link
Copy Markdown
Member

@SoonIter SoonIter commented Jan 9, 2026 •
edited
Loading

Summary

Related Issue

Checklist

  • Tests updated (or not required).
  • Documentation updated (or not required).

AI Summary

What Changed

Completely rewrote the SSG (Static Site Generation) documentation for both English and Chinese versions (website/docs/en/guide/basic/ssg.mdx and website/docs/zh/guide/basic/ssg.mdx).

Why

The original documentation was too shallow and didn't explain:

  • The difference between Dev mode (CSR) and Build mode (SSG/CSR)
  • What the build output structure looks like
  • Why code that works in Dev mode might fail in Build mode
  • How to troubleshoot common SSG build errors

Users were encountering build/deployment errors without understanding the root cause.

New Documentation Structure

  1. What is SSG - Clear concept introduction and advantages
  2. Dev Uses CSR, Build Uses SSG or CSR - Comparison table with commands, rendering modes, and use cases
  3. SSG vs CSR Output Comparison - Directory structure, HTML content differences, and loading flow differences
  4. Common Issues and Solutions - window is not defined, document is not defined, and Hydration Mismatch with code examples
  5. Configuration Options - How to enable/disable SSG
  6. Custom HTML Content - Using builderConfig.html.tags

Key Improvements

  • Added comparison table for Dev vs Build modes
  • Added HTML content examples showing SSG (pre-rendered) vs CSR (empty container) output
  • Added loading flow diagrams for both SSG and CSR
  • Added troubleshooting section with practical code solutions
  • Referenced Docusaurus SSG documentation style for depth and clarity

This PR was written using Vibe Kanban

@SoonIter
已完成 SSG 文档的重写。两个文件都已更新：
7fd1642 
**修改的文件：**
- `website/docs/zh/guide/basic/ssg.mdx` - 中文版
- `website/docs/en/guide/basic/ssg.mdx` - 英文版

**新文档结构：**

1. **什么是 SSG** - 概念介绍和优势
2. **Dev 与 Build 的对比** - 表格对比 + 命令说明 + 预览/部署方式
3. **SSG 与 CSR 产物的对比**
   - 产物目录结构
   - HTML 内容差异（核心区别）
   - 加载流程差异
4. **常见问题与解决方案**
   - `window is not defined` / `document is not defined`（含 3 种解决方案和代码示例）
   - Hydration Mismatch（含代码示例）
5. **配置选项** - `ssg: true/false`
6. **自定义 HTML 内容** - `builderConfig.html.tags`

新文档比原文档更加深入，帮助用户理解：
- SSG 框架的工作原理
- 为什么 Dev 模式正常但 Build 报错
- 如何正确解决构建问题
@SoonIter
已修复两个问题：
a1b0505 
1. **标题更新**：
   - 中文：`## Dev 与 Build 的对比` → `## Dev 使用 CSR，Build 使用 SSG 或 CSR`
   - 英文：`## Dev vs Build` → `## Dev Uses CSR, Build Uses SSG or CSR`

2. **导入路径修复**：
   - 中英文都从 `import { defineConfig } from 'rspress/config'` 改为 `import { defineConfig } from '@rspress/core'`
Copilot AI review requested due to automatic review settings January 9, 2026 07:36
@netlify
Copy link
Copy Markdown

netlify bot commented Jan 9, 2026 •
edited
Loading

✅ Deploy Preview for rspress-v2 ready!

Name Link
🔨 Latest commit 66a9855
🔍 Latest deploy log https://app.netlify.com/projects/rspress-v2/deploys/6960bd5fdfc06e000828841f
😎 Deploy Preview https://deploy-preview-2985--rspress-v2.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@SoonIter SoonIter changed the title 重写 guide/basic/ssg 文档 (vibe-kanban) docs(guide): rewrite SSG documentation with comprehensive explanations Jan 9, 2026
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Jan 9, 2026 •
edited
Loading

Rsdoctor Bundle Diff Analysis

Found 3 projects in monorepo, 3 projects with changes.

📊 Quick Summary
Project Total Size Change
node 9.8 MB +76.3 KB (0.8%)
node_md 1.3 MB 📈 +20.4 KB (+1.6%)
web 15.6 MB +77.6 KB (0.5%)
📋 Detailed Reports (Click to expand)

📁 node

Path: website/doc_build/diff-rsdoctor/node/rsdoctor-data.json

📌 Baseline Commit: 18f9b18ca0 | PR: #2984

Metric Current Baseline Change
📊 Total Size 9.8 MB 9.7 MB +76.3 KB (0.8%)
📄 JavaScript 0 B 0 B 0
🎨 CSS 0 B 0 B 0
🌐 HTML 9.8 MB 9.7 MB +76.3 KB (0.8%)
📁 Other Assets 0 B 0 B 0

📦 Download Diff Report: node Bundle Diff

📁 node_md

Path: website/doc_build/diff-rsdoctor/node_md/rsdoctor-data.json

📌 Baseline Commit: 18f9b18ca0 | PR: #2984

Metric Current Baseline Change
📊 Total Size 1.3 MB 1.2 MB +20.4 KB (+1.6%)
📄 JavaScript 0 B 0 B 0
🎨 CSS 0 B 0 B 0
🌐 HTML 0 B 0 B 0
📁 Other Assets 1.3 MB 1.2 MB +20.4 KB (+1.6%)

📦 Download Diff Report: node_md Bundle Diff

📁 web

Path: website/doc_build/diff-rsdoctor/web/rsdoctor-data.json

📌 Baseline Commit: 18f9b18ca0 | PR: #2984

Metric Current Baseline Change
📊 Total Size 15.6 MB 15.5 MB +77.6 KB (0.5%)
📄 JavaScript 14.9 MB 14.8 MB +66.6 KB (0.4%)
🎨 CSS 130.2 KB 130.2 KB 0
🌐 HTML 0 B 0 B 0
📁 Other Assets 575.0 KB 564.1 KB +11.0 KB (+1.9%)

📦 Download Diff Report: web Bundle Diff

Generated by Rsdoctor GitHub Action

Copilot AI reviewed Jan 9, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR comprehensively rewrites the SSG (Static Site Generation) documentation for both Chinese and English versions. The documentation was previously too shallow and could lead to build/deployment errors without clear guidance on how to resolve them.

Key changes:

  • Added detailed explanations of SSG concepts, advantages, and how it differs from CSR
  • Included clear comparisons of dev mode (CSR) vs build mode (SSG/CSR) with tables
  • Added troubleshooting sections for common issues (window is not defined, hydration mismatches) with code examples
  • Restructured content flow: What is SSG → Dev/Build modes → Output comparison → Common issues → Configuration

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File Description
website/docs/zh/guide/basic/ssg.mdx Complete rewrite of Chinese SSG documentation with comprehensive explanations, examples, and troubleshooting guidance
website/docs/en/guide/basic/ssg.mdx Complete rewrite of English SSG documentation maintaining consistency with Chinese version

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@SoonIter
已完成所有 review 反馈的修复：
4aaf097 
**中文版修改：**
1. "易于部署"部分添加了"无需部署服务器"
2. 标题改为"Dev 和 Build 下的区别"，并添加说明
3. Build 模式部分添加了预渲染原理说明

**英文版修改：**
1. "Easy to Deploy"部分添加了"with no server required"
2. 标题改为"Differences Between Dev and Build"，并添加说明
3. Build 模式部分添加了预渲染原理说明
@SoonIter
docs: upgrade
c6064ff
@SoonIter
docs: upgrade
0e22c33
@SoonIter
Copy link
Copy Markdown
Member Author

SoonIter commented Jan 9, 2026

@copilot open a new pull request to apply changes based on the comments in this thread

Copy link
Copy Markdown
Contributor

Copilot AI commented Jan 9, 2026

@SoonIter I've opened a new pull request, #2986, to work on those changes. Once the pull request is ready, I'll request review from you.

Copilot AI mentioned this pull request Jan 9, 2026
Merged
@SoonIter
docs(guide): apply review feedback for SSG documentation (#2986)
6415ed0 
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: SoonIter <79413249+SoonIter@users.noreply.github.com>
@SoonIter SoonIter enabled auto-merge (squash) January 9, 2026 08:20
@SoonIter SoonIter requested review from Timeless0911 and removed request for Timeless0911 January 9, 2026 08:21
@SoonIter SoonIter requested a review from Timeless0911 January 9, 2026 08:35
@SoonIter SoonIter merged commit 1bb56db into main Jan 9, 2026
8 checks passed
@SoonIter SoonIter deleted the syt-vibe-kanban/b5eb-guide-basic-ssg branch January 9, 2026 08:46
@github-actions github-actions bot mentioned this pull request Jan 9, 2026
Merged
2 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@Timeless0911 Timeless0911 Timeless0911 approved these changes

Assignees

No one assigned

Labels

change: docs

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@SoonIter @Timeless0911