Docs 文件结构与高级控制
与扁平的 Blog 列表不同，Docs 目录天生就是为了构建成体系的知识库而设计的。系统会自动把你建立的物理文件夹，在网页左侧转化为一个嵌套的树状导航菜单。
这篇文章将教你如何通过简单的配置，随心所欲地控制这棵“目录树”。
文件夹与 index.md
在通常情况下，一个包含 markdown 文件的文件夹会自动被解析为一个可展开的目录节点。然而，我们可以对这个“目录节点”进行高度定制。
让目录本身变成可点击的文章
默认情况下，点击一个目录，它仅仅会展开或折叠里面的子菜单。如果你希望点击目录名称时，能打开一个专门的“章节介绍主页”，你只需在对应文件夹内部新建一个 index.md，并在其顶部配置如下属性：
---title: '分类名称'is_article: true---此时，这个 index.md 就变成了该文件夹的“门面”，点击左侧该目录即可浏览这篇文章的内容。
单页面的专属文件夹收纳
有时候，你可能写了一篇很长的文章，并配有大量的专属图片。为了不让图片弄乱根目录，你想把文章和图片单独放进一个文件夹里。
只要你在这个文件夹里仅放了一篇开启了 is_article: true 的 index.md，系统会自动识别并把它在左侧菜单中显示为一篇普通的单页文章，去除了无用的展开/折叠箭头。
NOTE技术原理解析：单文件夹降维机制 在框架底层的
postProcessTree清洗机制中：如果扫描到一个物理文件夹内部只有自身代言人（index.md）而没有任何其他子内容，系统会触发“降维”操作：直接把该文件夹节点的数据结构type: 'folder'强制转化为type: 'file'，并在菜单渲染时移除其作为目录的包裹层属性。这使得该页面的 UI 表现与普通文章完全一致。
严格的排版利器：sidebar_position
为了让文档章节严格按照你的教学顺序（而不是凌乱的拼音字母）排列，请务必在文章或 index.md 的头部使用 sidebar_position 机制。
配置极其简单，直接填入数字即可（例如 1 代表排在最前面）：
---title: '第一章：入门'sidebar_position: 1---WARNING排版冲突零容忍 本框架禁止出现模糊的排版意图。如果同级目录下有两个文件的
sidebar_position值相同，系统会在终端立刻抛出致命错误并终止打包，确保你及时发现配置失误。
NOTE技术原理解析：底层排序规则 框架底层
sortTree的严密排序优先级如下：
- 带有
sidebar_position的项目享有最高特权，无条件排在未配置的项目之前。position相同的按数字大小升序排列。- 对于未配置
position的项目，优先按类型排序（文件夹folder永远在单文件file之前）。- 若类型相同，最后通过
localeCompare按文件名的本地字母表顺序兜底。
多语言 (i18n) 目录的轻松映射
当你的文档系统需要提供日文、韩文等多语言翻译时，操作逻辑也符合直觉。
假设你在主语言（中文）下有一个文档结构：
src/content/docs/前端教程/React/index.md
如果你想写日文版，你完全不需要去动配置文件，只要在专门的日语资源库（例如 ja 文件夹）中原封不动地复刻这套文件夹结构即可：
src/content/docs/ja/前端教程/React/index.md
系统会自动识别这种结构，并把翻译版的文章严丝合缝地嵌入到日文版网站相对应的左侧菜单节点中。
NOTE技术原理解析：目录结构虚拟剥离 在底层的树形构建逻辑中，当提取器解析路径时，如果发现前缀包含合法的非默认语言代码（如
ja/），它会调用parts.shift()在虚拟路径层面上剥离掉语言前缀，将其逻辑路径复原为与主语言一致的前端教程/React/index.md。接着系统依据这个“纯净版”路径将其精准挂载到对应的抽象节点下，实现了对用户完全透明的自动化翻译目录映射。
