Skip to content

docs(ssg): add 404.html to output structure and troubleshooting for page refresh 404#2987

Merged
SoonIter merged 7 commits intomainfrom
syt-vibe-kanban/d5b5-ssg-mdx-404-html
Jan 9, 2026
Merged

docs(ssg): add 404.html to output structure and troubleshooting for page refresh 404#2987
SoonIter merged 7 commits intomainfrom
syt-vibe-kanban/d5b5-ssg-mdx-404-html

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

Changes Made

This PR updates the SSG documentation (both Chinese and English) with the following improvements:

  1. Added 404.html to output directory structure

    • The 404.html file is now documented as part of the build output
    • Added explanation that this file is automatically generated by Rspress to handle non-existent routes

  2. Added troubleshooting section: "Page shows 404 after refresh"

    • Symptom: Navigating within the site works, but refreshing the page results in a 404 error
    • Cause: When refreshing or directly visiting a URL, the server may not have a corresponding file for that path
    • Solution: Most static hosting services (GitHub Pages, Netlify, Vercel, etc.) use 404.html by default to handle unmatched routes. For servers that don't handle this automatically, manual configuration is needed
    • Included a _redirects file example for hosting services that support it

Why These Changes Were Made

Users deploying Rspress sites to static hosting services may encounter 404 errors when refreshing pages or directly accessing URLs. This is a common deployment issue that needed documentation. The 404.html file generated by Rspress contains the complete application code and can correctly handle client-side routing.

This PR was written using Vibe Kanban

@SoonIter
已完成文档更新，主要改动：
fb1b86a 
**1. 产物目录结构 - 新增 `404.html`**

在产物目录结构中添加了 `404.html` 文件，并说明其用途。

**2. 新增 troubleshooting 章节「刷新页面时出现 404」**

- **现象**：站点内导航正常，刷新后 404
- **原因**：SPA 部署问题，客户端路由在刷新时服务器找不到对应文件
- **解决方案**：配置服务器重定向到 `404.html`，并提供了以下托管服务的配置示例：
  - Nginx
  - Vercel
  - Netlify
  - GitHub Pages
  - Apache

中英文文档均已同步更新。
@SoonIter
已根据 review comments 修改：
dc1074a 
1. 删除了 `以下是常见托管服务的配置方法：` / `Here are configuration methods for common hosting services:`
2. 删除了关于 SPA 模式的 tip 提示（因为 Rspress 本质上是 MPA）
3. 简化了原因说明，移除了关于 SPA 的描述
@SoonIter
已根据 review comments 修改：
331432d 
1. 删除了所有托管服务配置示例（Nginx、Vercel、Netlify、GitHub Pages、Apache）
2. 修改了解决方案描述：说明大部分静态托管服务默认会使用 `404.html` 处理未匹配路由，如果服务器没有自动处理才需要手动配置
@SoonIter
已添加 _redirects 文件配置示例，中英文文档均已更新。
c73c360
@SoonIter
已添加代码块的语言类型 txt 和文件路径 title docs/public/_redirects，中英文文档均已更新。
e17072e
Copilot AI review requested due to automatic review settings January 9, 2026 09:18
@netlify
Copy link
Copy Markdown

netlify bot commented Jan 9, 2026 •
edited
Loading

✅ Deploy Preview for rspress-v2 ready!

Name Link
🔨 Latest commit 38f687d
🔍 Latest deploy log https://app.netlify.com/projects/rspress-v2/deploys/6960cd2bd0fe1a000879079d
😎 Deploy Preview https://deploy-preview-2987--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.

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 enhances the SSG documentation by addressing a common SPA deployment issue where pages work correctly when navigating through links but show 404 errors upon refresh or direct URL access.

Key changes:

  • Documents the 404.html file in the build output structure
  • Adds a troubleshooting section explaining the 404 refresh issue and its solution
  • Provides a _redirects file configuration example for manual setup

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File Description
website/docs/zh/guide/basic/ssg.mdx Adds Chinese documentation for 404.html handling and SPA deployment troubleshooting
website/docs/en/guide/basic/ssg.mdx Adds English documentation for 404.html handling and SPA deployment troubleshooting

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

@SoonIter SoonIter changed the title ssg.mdx 文档更新，增加 404.html 和闪屏或者刷新 404 的 trouble shooting (vibe-kanban) docs(ssg): add 404.html to output structure and troubleshooting for page refresh 404 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 +8.5 KB (0.1%)
node_md 1.3 MB +5.7 KB (0.4%)
web 15.6 MB +9.5 KB (0.1%)
📋 Detailed Reports (Click to expand)

📁 node

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

📌 Baseline Commit: 1bb56dbace | PR: #2985

Metric Current Baseline Change
📊 Total Size 9.8 MB 9.8 MB +8.5 KB (0.1%)
📄 JavaScript 0 B 0 B 0
🎨 CSS 0 B 0 B 0
🌐 HTML 9.8 MB 9.8 MB +8.5 KB (0.1%)
📁 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: 1bb56dbace | PR: #2985

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

📦 Download Diff Report: node_md Bundle Diff

📁 web

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

📌 Baseline Commit: 1bb56dbace | PR: #2985

Metric Current Baseline Change
📊 Total Size 15.6 MB 15.6 MB +9.5 KB (0.1%)
📄 JavaScript 14.9 MB 14.9 MB +6.4 KB (0.0%)
🎨 CSS 130.2 KB 130.2 KB 0
🌐 HTML 0 B 0 B 0
📁 Other Assets 578.2 KB 575.0 KB +3.1 KB (0.5%)

📦 Download Diff Report: web Bundle Diff

Generated by Rsdoctor GitHub Action

SoonIter and others added 2 commits January 9, 2026 17:22
@SoonIter
Update website/docs/zh/guide/basic/ssg.mdx
bff77f7 
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
@SoonIter
已完成更新：
38f687d 
1. **ssg.mdx** - 为 404 troubleshooting 章节添加了锚点 `{#refresh-404}`
   - 中文：`### 刷新页面时出现 404 \{#refresh-404}`
   - 英文：`### Page shows 404 after refresh \{#refresh-404}`

2. **deploy.mdx** - 添加了 Troubleshooting 章节，链接到 ssg.mdx 的 #refresh-404
   - 中文：新增「常见问题」章节
   - 英文：新增「Troubleshooting」章节
@SoonIter SoonIter enabled auto-merge (squash) January 9, 2026 09:42
@SoonIter SoonIter requested a review from Timeless0911 January 9, 2026 09:43
@SoonIter SoonIter merged commit 968b671 into main Jan 9, 2026
8 checks passed
@SoonIter SoonIter deleted the syt-vibe-kanban/d5b5-ssg-mdx-404-html branch January 9, 2026 10:03
This was referenced Jan 12, 2026
Merged
Merged
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.

3 participants

@SoonIter @Timeless0911