Skip to content

docs: improve static assets documentation structure and clarifiy public folder usage#3011

Merged
Timeless0911 merged 8 commits intomainfrom
syt-vibe-kanban/f967-
Jan 15, 2026
Merged

docs: improve static assets documentation structure and clarifiy public folder usage#3011
Timeless0911 merged 8 commits intomainfrom
syt-vibe-kanban/f967-

Conversation

@SoonIter
Copy link
Copy Markdown
Member

@SoonIter SoonIter commented Jan 15, 2026 •
edited
Loading

Summary

docs: improve static assets documentation structure and clarifiy public folder usage

Related Issue

Checklist

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

AI Summary

Changes Made

This PR improves the "Static Assets" documentation for both Chinese and English versions:

Structure improvements:

  • Moved the "Static assets used in .md(x) files" section to the top of the page (right after the introduction) for better discoverability
  • Split the section into two clear subsections:
    • Regular static assets - for relative path references (assets in the same directory)
    • public directory - for absolute path references (assets in the public folder)

Content improvements:

  • Added reference to Rsbuild - Static Assets documentation
  • Added directory structure examples for both subsections to improve clarity
  • Clarified that public directory assets "are not processed during the build and are referenced directly via URL"
  • Simplified the explanation: relative imports are equivalent to using import image from "./demo.png"
  • Fixed incorrect module path: changed rspress/runtime to @rspress/core/runtime
  • Removed redundant relative path example (./public/demo.png) for public directory - only absolute paths should be used
  • Streamlined the base path note for better readability

This PR was written using Vibe Kanban

@SoonIter
已完成中英文文档的修改。主要变更如下：
ee85938 
**`.md(x)` 中使用的静态资源** 部分：

1. 拆分为两个子章节：
   - **普通静态资源** - 描述相对路径引用（同级目录下的资源）
   - **public 目录** - 描述绝对路径引用（public 目录下的资源）

2. 分别为两个子章节添加了目录结构示例

3. 增加了对 Rsbuild 静态资源处理文档的引用：
   - 中文：`[Rsbuild 静态资源处理](https://rsbuild.rs/zh/guide/basic/static-assets)`
   - 英文：`[Rsbuild static assets handling](https://rsbuild.rs/guide/basic/static-assets)`
@SoonIter
已完成修改。主要变更：
22cb842 
1. **将 `.md(x)` 中使用的静态资源章节移到介绍之后** - 现在是页面的第一个正式章节（在 Introduction 和 tip 之后）

2. **修改 public 目录的示例** - 删除了相对路径引用方式 `![](./public/demo.png)`，只保留绝对路径引用：
   ```mdx
   ![](/demo.png)
   ```

3. **保持 Rsbuild 静态资源处理的引用** - 中文链接到 `https://rsbuild.rs/zh/guide/basic/static-assets`，英文链接到 `https://rsbuild.rs/guide/basic/static-assets`
@SoonIter
已完成所有 Review Comments 的修改：
3936343 
1. **public 目录说明** - 增加了 "这些资源不会被构建，直接通过 URL 引用。" (英文: "These assets are not processed during the build and are referenced directly via URL.")

2. **修复 `rspress/runtime`** - 改为 `@rspress/core/runtime`

3. **Rsbuild 链接标题** - 改为 `[Rsbuild - 静态资源]` (英文: `[Rsbuild - Static Assets]`)，并删除了 "相对路径和绝对路径都是支持的。" 这句话
@SoonIter
已完成修改：
f807656 
1. **Line 61** - 将 "Rspress 将会根据 `.mdx` 文件路径和图片路径，自动找到图片并响应给浏览器。" 改为 "相当于直接使用 `import image from "./demo.png"`。"

2. **Line 84** - 将 "**需要注意的一种特殊情况是**，当你的站点配置了 `base` 路径，那么如果你要使用 `img` 标签的方式来引入绝对路径" 改为 "当你的站点配置了 `base` 路径并且要使用 `img` 标签的方式来引入绝对路径"

英文文档也已同步更新。
Copilot AI review requested due to automatic review settings January 15, 2026 10:07
@netlify
Copy link
Copy Markdown

netlify Bot commented Jan 15, 2026 •
edited
Loading

✅ Deploy Preview for rspress-v2 ready!

Name Link
🔨 Latest commit d6cf4d0
🔍 Latest deploy log https://app.netlify.com/projects/rspress-v2/deploys/6968cf584f1d4d0008e88367
😎 Deploy Preview https://deploy-preview-3011--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 文档修改：静态资源使用 (vibe-kanban) docs: improve static assets documentation structure and clarity Jan 15, 2026
Copilot AI reviewed Jan 15, 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 reorganizes the documentation for static asset usage in .md(x) files by separating it into two distinct sections: regular static assets (relative paths) and public directory (absolute paths). It also adds a reference to Rsbuild's static assets documentation as the underlying implementation.

Changes:

  • Reorganized the "Static assets used in .md(x) files" section into "Regular static assets" and "public directory" subsections
  • Added reference to Rsbuild documentation for static assets handling
  • Moved the section to appear earlier in the document (after the introductory tip)
  • Removed outdated example showing ![](./public/demo.png) usage

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/static-assets.mdx Restructured Chinese documentation with clearer subsections and removed incorrect public directory reference example
website/docs/en/guide/basic/static-assets.mdx Restructured English documentation with clearer subsections and removed incorrect public directory reference example
Comments suppressed due to low confidence (1)

website/docs/en/guide/basic/static-assets.mdx:155

  • Inconsistent quote style: The src value uses single quotes here (line 155), while other examples in the same file use unquoted strings (e.g., line 99). For consistency, this should match the pattern used elsewhere in the document.
    src: 'https://avatars.githubusercontent.com/u/56892468?s=200&v=4'

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

Comment thread website/docs/zh/guide/basic/static-assets.mdx Outdated
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Jan 15, 2026 •
edited
Loading

Rsdoctor Bundle Diff Analysis

Found 3 projects in monorepo, 3 projects with changes.

📊 Quick Summary
Project Total Size Change
node 10.5 MB +7.7 KB (0.1%)
web 15.9 MB +6.0 KB (0.0%)
node_md 1.3 MB +2.2 KB (0.2%)
📋 Detailed Reports (Click to expand)

📁 node

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

📌 Baseline Commit: 2546e80d32 | PR: #3009

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

📦 Download Diff Report: node Bundle Diff

📁 web

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

📌 Baseline Commit: 2546e80d32 | PR: #3009

Metric Current Baseline Change
📊 Total Size 15.9 MB 15.9 MB +6.0 KB (0.0%)
📄 JavaScript 15.1 MB 15.1 MB +4.9 KB (0.0%)
🎨 CSS 126.3 KB 126.3 KB 0
🌐 HTML 0 B 0 B 0
📁 Other Assets 716.2 KB 715.1 KB +1.2 KB (0.2%)

📦 Download Diff Report: web Bundle Diff

📁 node_md

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

📌 Baseline Commit: 2546e80d32 | PR: #3009

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

📦 Download Diff Report: node_md Bundle Diff

Generated by Rsdoctor GitHub Action

@SoonIter
已完成修改。public 目录部分现在包含：
3103b8c 
- 说明这些资源不会被构建，可以直接通过 URL 引用
- 开发服务器时托管在 `server.base` 根路径下的说明（带链接）
- 生产构建时拷贝到 dist 目录的说明（带链接）
- 常见用例示例：`robots.txt`、`manifest.json`、`favicon.ico`
@SoonIter SoonIter changed the title docs: improve static assets documentation structure and clarity docs: improve static assets documentation structure and clarifiy public folder usage Jan 15, 2026
@SoonIter SoonIter requested a review from Timeless0911 January 15, 2026 11:43
@Timeless0911 Timeless0911 merged commit 85708fe into main Jan 15, 2026
8 checks passed
@Timeless0911 Timeless0911 deleted the syt-vibe-kanban/f967- branch January 15, 2026 12:35
This was referenced Jan 15, 2026
Closed
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