Skip to content

docs: add troubleshooting tip for @rspress/core/theme-original export errors in migration guide#2984

Merged
SoonIter merged 3 commits intomainfrom
syt-vibe-kanban/40ee-rspress-1-x-rspr
Jan 9, 2026
Merged

docs: add troubleshooting tip for @rspress/core/theme-original export errors in migration guide#2984
SoonIter merged 3 commits intomainfrom
syt-vibe-kanban/40ee-rspress-1-x-rspr

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 changes were made

Added a troubleshooting tip to both the Chinese and English Rspress 1.x migration guide documents. The tip explains a common error that users encounter when migrating custom themes to Rspress V2.

Why they were made

When users migrate from Rspress 1.x to V2, they may encounter ESModulesLinkingError errors about missing exports (like SvgWrapper or Banner) from @theme or @rspress/core/theme. This happens when users override the theme in the theme folder but don't use @rspress/core/theme-original to re-export all the original theme components.

Implementation details

  • Added a :::tip block in the "Theme import paths" section of the migration guide
  • Includes example error messages to help users identify the issue
  • Provides clear guidance to use @rspress/core/theme-original and export all components correctly
  • Updated both website/docs/zh/guide/migration/rspress-v1.mdx and website/docs/en/guide/migration/rspress-v1.mdx

This PR was written using Vibe Kanban

@SoonIter
已完成中英文两个迁移文档的更新。我在 "主题导入路径说明" 部分后面添加了一个 :::tip 提示框，说明了当遇到 @theme …
3ce1e1d 
…或 `@rspress/core/theme` 缺少导出的报错时，原因是在 theme 文件夹下覆盖主题时没有使用 `@rspress/core/theme-original`，并附上了示例错误信息。

修改摘要：
- **中文文档** (`website/docs/zh/guide/migration/rspress-v1.mdx`): 第 166-178 行
- **英文文档** (`website/docs/en/guide/migration/rspress-v1.mdx`): 第 166-178 行
Copilot AI review requested due to automatic review settings January 9, 2026 06:50
@netlify
Copy link
Copy Markdown

netlify bot commented Jan 9, 2026 •
edited
Loading

✅ Deploy Preview for rspress-v2 ready!

Name Link
🔨 Latest commit 7f47165
🔍 Latest deploy log https://app.netlify.com/projects/rspress-v2/deploys/6960a74c42eb61000832c7d7
😎 Deploy Preview https://deploy-preview-2984--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 补充文档，从 Rspress 1.x 迁移中 @rspress/core/theme-original 相关报错 (vibe-kanban) docs: add troubleshooting tip for @rspress/core/theme-original export errors in migration guide Jan 9, 2026
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 adds helpful troubleshooting documentation to the Rspress v1 to v2 migration guide. It addresses common errors users encounter when migrating theme customizations, specifically when they forget to use @rspress/core/theme-original when overriding themes.

  • Adds a tip box explaining errors related to missing exports from @theme or @rspress/core/theme
  • Includes concrete error message examples to help users identify the issue
  • Provides clear guidance on the solution

Reviewed changes

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

File Description
website/docs/zh/guide/migration/rspress-v1.mdx Adds Chinese documentation for theme-original migration errors with examples and solutions
website/docs/en/guide/migration/rspress-v1.mdx Adds English documentation for theme-original migration errors with examples and solutions

💡 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 9, 2026 •
edited
Loading

Rsdoctor Bundle Diff Analysis

⚠️ Note: The latest commit (bf0e42ff59) does not have baseline artifacts. Using commit 6f272df7d8 for baseline comparison instead. If this seems incorrect, please wait a few minutes and try rerunning the workflow.

Found 3 projects in monorepo, 3 projects with changes.

📊 Quick Summary
Project Total Size Change
node 9.7 MB +5.4 KB (0.1%)
node_md 1.2 MB +2.7 KB (0.2%)
web 15.5 MB +4.1 KB (0.0%)
📋 Detailed Reports (Click to expand)

📁 node

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

📌 Baseline Commit: 6f272df7d8 | PR: #2966

Metric Current Baseline Change
📊 Total Size 9.7 MB 9.7 MB +5.4 KB (0.1%)
📄 JavaScript 0 B 0 B 0
🎨 CSS 0 B 0 B 0
🌐 HTML 9.7 MB 9.7 MB +5.4 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: 6f272df7d8 | PR: #2966

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

📦 Download Diff Report: node_md Bundle Diff

📁 web

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

📌 Baseline Commit: 6f272df7d8 | PR: #2966

Metric Current Baseline Change
📊 Total Size 15.5 MB 15.5 MB +4.1 KB (0.0%)
📄 JavaScript 14.8 MB 14.8 MB +2.8 KB (0.0%)
🎨 CSS 130.2 KB 130.2 KB 0
🌐 HTML 0 B 0 B 0
📁 Other Assets 564.1 KB 562.7 KB +1.3 KB (0.2%)

📦 Download Diff Report: web Bundle Diff

Generated by Rsdoctor GitHub Action

@SoonIter SoonIter requested a review from Timeless0911 January 9, 2026 06:52
@SoonIter SoonIter enabled auto-merge (squash) January 9, 2026 06:53
Timeless0911
Timeless0911 previously approved these changes Jan 9, 2026
View reviewed changes
@SoonIter SoonIter disabled auto-merge January 9, 2026 06:55
@SoonIter SoonIter requested a review from Timeless0911 January 9, 2026 06:57
@SoonIter SoonIter enabled auto-merge (squash) January 9, 2026 06:57
@SoonIter SoonIter merged commit 18f9b18 into main Jan 9, 2026
8 checks passed
@SoonIter SoonIter deleted the syt-vibe-kanban/40ee-rspress-1-x-rspr branch January 9, 2026 07:12
@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.

3 participants

@SoonIter @Timeless0911