参考集合用于承载稳定、适合查阅的材料。把它写得客观、紧凑、易于扫描，读者就能在 /docs 中的概念页与这里的细节页之间自然切换，而不用改变理解方式。

这里适合放什么

参考分区适合承载那些读者会反复查阅的信息：

  • 认证规则
  • 请求与响应结构
  • 错误格式
  • 字段级约束

叙事式背景、入门建议和编辑性说明，通常更适合放在 /docs 中。

编写模式

参考页面与文档页面使用相同的 frontmatter 约定：

---
title: Authentication
description: Explain how clients prove identity before making requests.
section: Core
order: 1
---

这样一来，共享侧边栏、页面元数据以及上一页/下一页导航都可以自动生成。

建议结构

大多数团队都会受益于一个简单的拆分：

  1. 用 /docs 承载入门与工作流说明。
  2. 用 /reference 承载稳定定义与查阅型材料。
  3. 当指南依赖具体 API 结构时，在两者之间建立链接。

如果你想先看一个具体例子，可以从 Authentication 开始。