docs: update auto-nav-sidebar to recommend index.mdx for dir, index convention#2978
docs: update auto-nav-sidebar to recommend index.mdx for dir, index convention#2978
Conversation
1. **将 tip 移动到 `dir` 部分** - 从 `divider` 部分移除，放到 `dir` 部分的示例代码后面 2. **更新推荐用法** - 不再推荐同名文件方式，改为推荐在目录内创建 `index.mdx` 3. **更新文件树示例** - 使用 tree 代码块展示： ``` basic ├── index.mdx ├── getting-started.mdx └── _meta.json ``` 4. **说明 `_meta.json` 内容** - 添加了 `["getting-started"]`（不需要包含 `index`）的说明
✅ Deploy Preview for rspress-v2 ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Rsdoctor Bundle Diff AnalysisFound 3 projects in monorepo, 3 projects with changes. 📊 Quick Summary
📋 Detailed Reports (Click to expand)📁 nodePath:
📦 Download Diff Report: node Bundle Diff 📁 node_mdPath:
📦 Download Diff Report: node_md Bundle Diff 📁 webPath:
📦 Download Diff Report: web Bundle Diff Generated by Rsdoctor GitHub Action |
1. **删除了同名文件方式** - 移除了"在上级目录新建同名文件 `theme.md`"的方式 2. **只保留 `index.md` 方式** - 推荐在目录内创建 `index.md` 3. **优化文件树格式** - 使用规范的 tree 格式，移除了 `// ...` 注释 4. **添加 JSON 代码块标题** - `title="theme/_meta.json"`
There was a problem hiding this comment.
Pull request overview
This PR updates the documentation for the auto-nav-sidebar feature to reflect current best practices. The tip about displaying a document when clicking a sidebar directory has been moved from the "divider" section to the "dir" section and updated to recommend the index.mdx approach over the deprecated same-name sibling file approach.
- Moved tip section from after "divider" to after "dir" type definition for better context
- Updated recommendation from creating sibling files with same name to using
index.mdxinside directories - Updated file tree examples to demonstrate the new recommended approach
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| website/docs/zh/guide/basic/auto-nav-sidebar.mdx | Chinese documentation updated with repositioned tip and new index.mdx recommendation |
| website/docs/en/guide/basic/auto-nav-sidebar.mdx | English documentation updated with repositioned tip and new index.mdx recommendation |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
1. **更新文件树结构** - 添加了 `guide` 子目录，展示更完整的层级关系
2. **添加两个 `_meta.json` 示例**：
- `basic/_meta.json`: `[{ "type": "dir", "name": "guide" }]`
- `guide/_meta.json`: `["getting-started"]`
3. **更新说明文字** - 改为"点击 `Guide` 目录时"
Summary
Update the auto-nav-sidebar documentation to recommend using
index.mdxinside directories instead of creating a same-named file at the same level.Related Issue
Checklist
AI Summary
Changes Made
Documentation updates for both English and Chinese versions:
Moved the tip from the
dividersection to thedirsection, which is more contextually appropriate since it relates to directory behaviorUpdated the recommended approach for displaying a document when clicking on a sidebar directory:
md(x)file at the same level as the directory (e.g.,advanced.mdxalongsideadvanced/)index.mdxfile inside the directory (e.g.,basic/index.mdx)Improved the example with a clearer file tree structure showing
docs/basic/containingindex.mdx,getting-started.mdx, and_meta.jsonAdded code block showing the
_meta.jsoncontent with explanation that it only needs to list the other documents (notindex)Why These Changes
The
index.mdxapproach is the recommended pattern as it:This PR was written using Vibe Kanban