自动文件夹扫描功能使用指南

功能概述

系统现在支持自动扫描 /content 目录下的所有文件夹（排除 files 文件夹），并为每个文件夹自动生成文档中心页面和导航菜单。

📌 前置知识：建议先阅读文档中心组件指南了解基本用法，然后阅读高级功能使用了解双向链接等特性。

核心特性

1. 自动发现文件夹

系统会自动检测以下文件夹：

✅ content/posts/ - 博客文章（已有专门页面）
✅ content/pages/ - 文档页面（已有专门页面）
✅ content/tutorials/ - 教程（新建文件夹示例）
✅ 任何其他新建的文件夹

排除：content/files/ 文件夹（用于存储 PDF 等文件）

2. index.md 配置

每个文件夹可以包含一个 index.md 文件来配置该文件夹的展示方式。

index.md 示例

---
title: 教程中心
description: 系统使用教程和指南
type: page
enableTree: true
showBreadcrumb: true
layout: sidebar
icon: 📚
order: 10
---

# 教程中心

这里是教程首页的内容...

可用配置字段

字段	类型	说明	默认值
`title`	string	文件夹标题，会显示在导航栏	文件夹名称（首字母大写）
`description`	string	文件夹描述	空
`type`	string	文档类型（page/post）	page
`enableTree`	boolean	是否启用树形结构	false
`showBreadcrumb`	boolean	是否显示面包屑导航	false
`layout`	string	布局模式（sidebar/dropdown/tabs）	sidebar
`icon`	string	图标（可选）	null
`order`	number	导航栏中的排序顺序	999

3. 文档排序

系统支持多层级的智能排序，优先级如下：

排序优先级

置顶 (pinned 或 sticky)
优先级 (priority)
顺序 (order)
文件名字母顺序 (A-Z)

文档 Front Matter 示例

---
title: 快速开始
order: 1
pinned: true
priority: 10
collection: tutorials
---

可用字段

字段	类型	说明
`pinned`	boolean	是否置顶
`sticky`	boolean	是否置顶（同 pinned）
`priority`	number	优先级（数值越大越靠前）
`order`	number	排序序号（数值越小越靠前）
`collection`	string	所属集合（文件夹名称）

4. 树形结构和面包屑

通过 parent 字段建立文档的层级关系。

示例：父子文档

父文档 (tutorial-index.md):

---
title: 教程索引
id: tutorial-index
collection: tutorials
order: 1
---

子文档 (basic-tutorial.md):

---
title: 基础教程
parent: tutorial-index
collection: tutorials
order: 1
---

子文档 (advanced-tutorial.md):

---
title: 高级教程
parent: tutorial-index
collection: tutorials
order: 2
---

这样会生成如下树形结构：

📚 教程索引
  ├─ 📄 基础教程
  └─ 📄 高级教程

使用步骤

步骤 1: 创建新文件夹

在 content/ 目录下创建新文件夹：

mkdir content/tutorials

步骤 2: 创建 index.md（可选）

touch content/tutorials/index.md

编辑 index.md：

---
title: 教程中心
description: 系统教程和指南
enableTree: true
showBreadcrumb: true
order: 10
---

# 教程中心

欢迎！

步骤 3: 添加文档

创建文档文件：

touch content/tutorials/getting-started.md
touch content/tutorials/advanced.md

编辑文档：

---
title: 快速开始
order: 1
pinned: true
collection: tutorials
---

# 快速开始

内容...

步骤 4: 启动应用

npm run dev

系统会自动：

✅ 扫描发现 tutorials 文件夹
✅ 读取 index.md 配置
✅ 生成路由 /tutorials
✅ 在导航栏添加"教程中心"链接
✅ 按配置展示文档列表

完整示例

文件结构

content/
├── posts/           # 博客（已有）
├── pages/           # 文档（已有）
├── files/           # 文件（排除）
└── tutorials/       # 新建教程文件夹
    ├── index.md     # 文件夹配置
    ├── getting-started.md
    ├── advanced-features.md
    └── api/
        ├── index.md
        ├── authentication.md
        └── endpoints.md

index.md 配置

---
title: 教程中心
description: 完整的系统教程
type: page
enableTree: true
showBreadcrumb: true
layout: sidebar
order: 5
---

# 教程中心
...

文档配置示例

置顶文档:

---
title: ⭐ 重要通知
pinned: true
priority: 100
---

高优先级文档:

---
title: 快速开始
priority: 50
order: 1
---

普通文档:

---
title: 进阶指南
order: 10
---

子文档:

---
title: API 认证
parent: api-index
order: 1
---

注意事项

文件夹命名：使用小写字母和连字符，如 my-tutorials
collection 字段：应与文件夹名称一致
id 字段：用于建立父子关系时必须唯一
排序字段：数值型字段使用数字，不要加引号
布尔字段：使用 true 或 false，不要加引号

故障排查

问题：新文件夹没有出现在导航栏

检查：

文件夹是否在 content/ 目录下
文件夹内是否有 .md 文件
是否重启了开发服务器

问题：排序不正确

检查：

front matter 格式是否正确
数值字段是否有引号
collection 字段是否与文件夹名匹配

问题：树形结构不显示

检查：

index.md 中 enableTree 是否为 true
parent 字段是否指向正确的 id
父文档是否存在

技术细节

工作原理

应用启动时，folderScanner.js 扫描 content 目录
读取每个文件夹的 index.md 配置
生成文件夹配置数组
App.jsx 根据配置动态创建路由
Header.jsx 根据配置动态添加导航链接
用户访问路由时，DynamicDocumentPage 渲染相应的文档中心

总结

现在您可以：

✅ 在 content/ 下创建任意文件夹
✅ 使用 index.md 自定义文件夹展示
✅ 使用 front matter 控制文档排序
✅ 建立树形结构和面包屑导航
✅ 自动生成路由和导航

无需修改任何代码！🎉

自动文件夹扫描指南