Skip to content

docs: improve conventional route documentation with better examples and best practices#2995

Merged
SoonIter merged 10 commits intomainfrom
syt-vibe-kanban/0726-
Jan 13, 2026
Merged

docs: improve conventional route documentation with better examples and best practices#2995
SoonIter merged 10 commits intomainfrom
syt-vibe-kanban/0726-

Conversation

@SoonIter
Copy link
Copy Markdown
Member

@SoonIter SoonIter commented Jan 12, 2026 •
edited
Loading

Summary

Related Issue

Checklist

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

AI Summary

Changes Made

This PR improves the conventional route documentation for both Chinese and English versions:

File structure examples:

  • Updated the file structure example to be more consistent with the mapping rules table
  • Added foo/index.md to demonstrate directory index routing
  • Added zoo.md to show simple file routing
  • Removed conflicting foo.md and foo/index.md combination

New warning section:

  • Added a warning block explaining that files and folders with the same name cause routing conflicts (e.g., foo.md and foo/index.md cannot coexist)

Best practices section:

  • Enhanced best practices with detailed guidance on organizing .tsx and .mdx files in the docs directory
  • Added tip explaining the need to use route.exclude for non-route files
  • Added comprehensive project structure example with components/ and fragments/ directories
  • Added tsconfig.json configuration example

Code organization:

  • Extracted common fragments into reusable MDX components (file-structure.mdx, route-convention.mdx)
  • Added new section about default exclusion of files starting with _

Why These Changes

The original documentation had inconsistencies between the file structure example and the mapping rules table. The examples also showed a conflicting file structure that would cause routing issues in practice. These updates make the documentation clearer, more accurate, and provide better guidance for users organizing their Rspress projects.

This PR was written using Vibe Kanban

@SoonIter
已更新文档。现在文件结构示例中包含了 zoo/index.md，与下方映射规则表格中的 /zoo/index.md 示例保持一致。
fb43e36
@SoonIter
已添加 foo/index.md 到文件结构示例中。现在示例包含：
40bfd46 
- `foo/bar.md`
- `foo/index.md`
- `foo.md`
- `zoo/index.md`
@SoonIter
已将英文文档同步更新，包括：
b832a81 
1. 更新了路由说明，添加了 `/foo/index.md` 的路由路径说明
2. 更新了自定义行为部分的代码示例和注释
3. 添加了最佳实践的 tip 提示框
4. 添加了完整的项目结构示例、rspress.config.ts 和 tsconfig.json 配置示例
@SoonIter
docs: upgrade
2716590
@SoonIter
docs: upgrade
0510c9e
Copilot AI review requested due to automatic review settings January 12, 2026 06:06
@netlify
Copy link
Copy Markdown

netlify bot commented Jan 12, 2026 •
edited
Loading

✅ Deploy Preview for rspress-v2 ready!

Name Link
🔨 Latest commit 72d34e3
🔍 Latest deploy log https://app.netlify.com/projects/rspress-v2/deploys/6964a087429859000888ce88
😎 Deploy Preview https://deploy-preview-2995--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 12, 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 updates the Rspress documentation to address missing file examples and reorganize documentation structure. The main purpose is to add the missing zoo/index.md example mentioned in the routing convention documentation and improve the overall documentation organization by extracting reusable fragments.

Changes:

  • Added missing zoo/index.md example to the file structure documentation in conventional routing pages
  • Extracted common documentation fragments into reusable MDX files for better maintainability
  • Reorganized component structure by moving Border component to a shared location
  • Enhanced routing examples with cleaner URL configuration examples
  • Updated both Chinese (zh) and English (en) documentation consistently

Reviewed changes

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

Show a summary per file
File Description
website/tsconfig.json Removed redundant jsx: "preserve" configuration
website/docs/zh/guide/use-mdx/components.mdx Updated section headings, extracted routing convention content to fragment, updated import paths
website/docs/zh/guide/use-mdx/_escape-hatch.tsx Enhanced to use getCustomMDXComponent for better MDX component handling
website/docs/zh/guide/use-mdx/_button.mdx Deleted and moved to fragments directory
website/docs/zh/guide/use-mdx/_Border.tsx Deleted and moved to shared components directory
website/docs/zh/guide/basic/i18n.mdx Added file structure example section
website/docs/zh/guide/basic/custom-theme.mdx Added file structure example section
website/docs/zh/guide/basic/conventional-route.mdx Added zoo/index.md example, enhanced routing table, extracted content to fragments
website/docs/zh/fragments/route-convention.mdx New reusable fragment for routing convention documentation
website/docs/zh/fragments/file-structure.mdx New reusable fragment showing best practice file structure
website/docs/zh/fragments/_button.mdx New button example fragment for documentation
website/docs/en/guide/use-mdx/components.mdx English version of zh changes
website/docs/en/guide/use-mdx/_escape-hatch.tsx English version of zh changes
website/docs/en/guide/use-mdx/_button.mdx Deleted and moved to fragments
website/docs/en/guide/basic/i18n.mdx Added file structure example section
website/docs/en/guide/basic/custom-theme.mdx Added file structure example section
website/docs/en/guide/basic/conventional-route.mdx Added zoo/index.md example, enhanced routing documentation
website/docs/en/fragments/route-convention.mdx English version of routing convention fragment
website/docs/en/fragments/file-structure.mdx English version of file structure fragment
website/docs/en/fragments/_button.mdx English version of button example fragment
website/docs/components/Border.tsx Moved to shared location and enhanced with border radius styling

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

@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Jan 12, 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 +53.0 KB (0.5%)
node_md 1.3 MB +10.3 KB (0.8%)
web 15.6 MB +42.0 KB (0.3%)
📋 Detailed Reports (Click to expand)

📁 node

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

📌 Baseline Commit: 82a242261a | PR: #2994

Metric Current Baseline Change
📊 Total Size 9.8 MB 9.8 MB +53.0 KB (0.5%)
📄 JavaScript 0 B 0 B 0
🎨 CSS 0 B 0 B 0
🌐 HTML 9.8 MB 9.8 MB +53.0 KB (0.5%)
📁 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: 82a242261a | PR: #2994

Metric Current Baseline Change
📊 Total Size 1.3 MB 1.3 MB +10.3 KB (0.8%)
📄 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 +10.3 KB (0.8%)

📦 Download Diff Report: node_md Bundle Diff

📁 web

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

📌 Baseline Commit: 82a242261a | PR: #2994

Metric Current Baseline Change
📊 Total Size 15.6 MB 15.6 MB +42.0 KB (0.3%)
📄 JavaScript 14.9 MB 14.9 MB +39.2 KB (0.3%)
🎨 CSS 130.2 KB 130.2 KB 0
🌐 HTML 0 B 0 B 0
📁 Other Assets 580.9 KB 578.2 KB +2.7 KB (0.5%)

📦 Download Diff Report: web Bundle Diff

Generated by Rsdoctor GitHub Action

SoonIter and others added 2 commits January 12, 2026 14:19
@SoonIter
Apply suggestion from @Copilot
42a8d83 
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
@SoonIter
docs: clarify
d305292
@SoonIter SoonIter changed the title 更新文档 (vibe-kanban) docs: improve conventional route documentation with better examples and best practices Jan 12, 2026
@SoonIter SoonIter requested a review from Timeless0911 January 13, 2026 03:38
@SoonIter SoonIter merged commit 86250fc into main Jan 13, 2026
8 checks passed
@SoonIter SoonIter deleted the syt-vibe-kanban/0726- branch January 13, 2026 03:41
This was referenced Jan 13, 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