Fumadocs项目中基于Frontmatter的MDX文件过滤方案

在实际文档系统开发中，我们经常需要根据文档内容本身来控制其是否应该被构建和发布。Fumadocs作为一个现代化的文档工具链，提供了灵活的解决方案来处理这种需求。

核心需求场景

假设我们有一批MDX格式的文档，其中部分文档包含敏感信息或处于草稿状态，不应该被公开发布。传统做法是在构建流程中通过文件路径或命名规则来排除，但这种方式不够直观且维护困难。

更理想的解决方案是让文档自身声明是否应该被发布，例如通过Frontmatter元数据：

---
title: 产品使用指南
public: true
---

Fumadocs的解决方案

Fumadocs提供了两种不同层级的实现方式：

1. 构建时过滤（推荐方案）

在项目的source配置文件中，我们可以对已加载的文档集合进行过滤：

import { docs, meta } from '@/.source';
import { createMDXSource } from 'fumadocs-mdx';
import { loader } from 'fumadocs-core/source';

export const source = loader({
  baseUrl: '/docs',
  source: createMDXSource(
    docs.filter(doc => doc._exports.frontmatter.public === true),
    meta
  ),
});

这种方式的优势在于：

• 不改变底层文件读取机制，保持构建效率
• 过滤逻辑清晰可见，易于维护
• 可以与草稿模式等其他功能协同工作

2. 底层文件处理方案（备选）

虽然技术上可以在MDX生成阶段进行过滤（修改generateJS函数），但Fumadocs团队指出这种方式：

• 仍然需要完整读取文件内容
• 增加了系统复杂性
• 不如上层过滤方案灵活

技术实现细节

当使用推荐方案时，关键点在于理解Fumadocs的数据流：

1. 所有MDX文件首先会被解析并加载到内存中
2. 生成的docs对象包含完整的文档信息和元数据
3. 过滤操作发生在文档集合已经加载完成后
4. 最终只将符合条件的文档传递给渲染系统

这种架构确保了：

• 开发模式下仍能访问所有文档
• 构建时可以精确控制输出内容
• 不影响其他功能如全文搜索等

最佳实践建议

对于实际项目部署，建议：

1. 为团队制定清晰的Frontmatter规范
2. 考虑添加TypeScript类型定义确保元数据一致性
3. 在CI流程中加入验证步骤，检查关键文档的public标记
4. 可以扩展过滤逻辑，结合环境变量实现多环境发布控制

通过这种基于内容的过滤机制，Fumadocs为文档工程化提供了更精细的控制能力，使文档管理更加智能和高效。