Docs _meta.json 用法与规范

详细说明 iflux-art docs 站点中 _meta.json 配置文件的作用、格式、多级嵌套机制，以及标题优先级和侧边栏渲染逻辑。

Docs 站点的侧边栏导航不是自动生成的，而是通过每个目录下的 _meta.json 文件来配置。这套机制决定了侧边栏的显示名称、排列顺序和层级结构。

一、什么是 _meta.json

_meta.json 是一个放在内容目录中的 JSON 配置文件，每个目录最多放一个。它的核心作用有两个：

• 映射显示名称 — 将文件名或目录名映射为更友好的名称（如 wsl2 → WSL 2 安装与通用配置指南）
• 控制排序 — 严格按照 JSON 中键的声明顺序渲染侧边栏

以点开头的目录（如 .obsidian）和 _meta.json 本身不会被纳入文档扫描。

二、基本格式

最简单的 _meta.json 是一个扁平的键值对对象，键为目录名或文件名（不含扩展名），值为显示名称：

{  "ollama": "Ollama 快速入门",  "docker": "Docker 快速入门"}

对应目录结构：

local/ ├── _meta.json ├── ollama.md └── docker.md

侧边栏会将 ollama 显示为 "Ollama 快速入门"，docker 显示为 "Docker 快速入门"，且 ollama 排在 docker 前面。

三、多级嵌套

Docs 支持任意层级的目录嵌套，每一层都可以有自己的 _meta.json。

项目实际结构

以当前项目为例：

src/content/ ├── _meta.json ← 第 1 层：控制顶级分类 ├── index.mdx ├── grammar/ │ ├── _meta.json ← 第 2 层：控制 grammar 下的文档 │ ├── markdown.md │ └── ... ├── system/ │ ├── _meta.json ← 第 2 层：控制 system 下的文档 │ ├── linux.md │ └── ... ├── agent/ │ ├── _meta.json ← 第 2 层：控制 agent 下的子分类 │ ├── claude-code/ │ │ ├── _meta.json ← 第 3 层：控制 claude-code 下的文档 │ │ └── wsl2-cc.md │ └── hermes-agent/ │ ├── _meta.json ← 第 3 层：控制 hermes-agent 下的文档 │ ├── wsl2-hermes.md │ └── hermes-feishu.md └── local/ └── _meta.json ← 第 2 层：控制 local 下的文档

第 1 层 — 顶级分类

content/_meta.json 控制侧边栏最外层的分类入口：

{  "grammar": "语法基础",  "system": "操作系统",  "agent": "智能体",  "local": "本地部署",  "operation": "运营"}

侧边栏会依次显示"语法基础"、"操作系统"、"智能体"、"本地部署"、"运营"五个顶级入口。

第 2 层 — 分类下的文档或子分类

以 agent/_meta.json 为例，它控制"智能体"分类下的子项：

{  "hermes-agent": "Hermes Agent",  "openclaw": "OpenClaw",  "claude-code": "Claude Code"}

这里的键 hermes-agent 和 claude-code 是目录名，openclaw 也是目录名。它们在侧边栏中作为可展开的子分类显示。

对于只包含文档文件不包含子目录的分类，如 system/_meta.json：

{  "linux": "Linux 发行版对比",  "wsl2": "WSL 2 安装与通用配置指南",  "arch": "WSL 2 安装 Arch Linux 完整指南"}

这里的键都是 .md 文件名（不含扩展名），侧边栏直接显示为文档链接。

第 3 层 — 子分类下的文档

agent/hermes-agent/_meta.json 控制子分类下的具体文档：

{  "wsl2-hermes": "在 WSL 2 上安装 Hermes Agent",  "hermes-feishu": "配置 Hermes Agent 连接飞书"}

四、标题优先级

侧边栏显示的标题有明确的优先级，从高到低：

1. _meta.json 中配置的名称 — 最高优先级，无论是字符串还是对象中的 title
2. Frontmatter 中的 title 字段
3. 文件名（去掉扩展名） — 降级兜底

以 grammar/markdown.md 为例，即使文件 frontmatter 中写了 title: Markdown 快速入门，侧边栏也会优先使用 _meta.json 中配置的 "markdown": "Markdown 快速入门"。

五、未配置的项

如果某个目录或文件没有在 _meta.json 中列出，它仍然会出现在侧边栏中，只是行为如下：

也就是说，_meta.json 是可选的。不加也能正常工作，只是排序和命名不可控。

六、添加新文档的流程

在已有分类下添加文档

假设要在 grammar 分类下添加一个 typescript.md：

1. 创建文件 src/content/grammar/typescript.md 并编写内容
2. 编辑 src/content/grammar/_meta.json，在合适位置添加条目：

{  "markdown": "Markdown 快速入门",  "json": "JSON 快速入门",  "typescript": "TypeScript 快速入门",  "git": "Git 快速入门",  "curl": "Curl 快速入门",  "makefile": "Makefile 快速入门",  "ssh": "SSH 快速入门",  "vim": "Vim 快速入门",  "regex": "正则表达式快速入门"}

条目的位置决定了它在侧边栏中的排序位置。

添加新的顶级分类

假设要添加一个 database 分类：

1. 创建目录 src/content/database/
2. 在 src/content/database/ 下创建文档文件
3. 创建 src/content/database/_meta.json：

{  "mysql": "MySQL 快速入门",  "redis": "Redis 快速入门"}

1. 编辑 src/content/_meta.json，添加新分类：

{  "grammar": "语法基础",  "system": "操作系统",  "agent": "智能体",  "local": "本地部署",  "operation": "运营",  "database": "数据库"}

添加多级子分类

假设要在 agent 下添加一个 cursor 子分类：

1. 创建目录 src/content/agent/cursor/
2. 在其下创建文档文件，如 setup.md
3. 创建 src/content/agent/cursor/_meta.json：

{  "setup": "Cursor 安装与配置"}

1. 编辑 src/content/agent/_meta.json，添加条目：

{  "hermes-agent": "Hermes Agent",  "cursor": "Cursor",  "openclaw": "OpenClaw",  "claude-code": "Claude Code"}

七、注意事项

文件名 vs 键名

_meta.json 中的键名必须与文件名或目录名完全匹配（不含扩展名）。文件名 wsl2-cc.md 对应的键是 wsl2-cc，目录名 hermes-agent 对应的键是 hermes-agent。大小写敏感。

隐藏文档

如果某篇文档不想出现在侧边栏中，有两种方式：

1. 在 frontmatter 中设置 display: hidden
2. 不在 _meta.json 中列出（但这种方式下文档仍可能在其他地方被访问到）

目录和文档同名冲突

如果存在 agent/claude-code.md 文件和 agent/claude-code/ 目录同时存在，构建时会优先保留文档文件，目录会被忽略。避免这种命名冲突。

JSON 格式

_meta.json 必须是合法的 JSON 格式。注意以下常见错误：

• 键名必须用双引号，不能用单引号
• 不能有尾逗号（trailing comma）
• 不能有注释（JSON 不支持注释）