这些内容分区从设计上就是 Markdown 优先。写作者可以把注意力放在清晰结构和可复用表述上，而布局则会从 frontmatter 中提取导航和页面元数据。

Frontmatter 约定

src/content/en-US/docs/、src/content/zh-CN/docs/、src/content/en-US/reference/ 或 src/content/zh-CN/reference/ 下的每个页面，都应该声明同样的四个字段：

---
title: Content Authoring
description: Explain how markdown pages are written and grouped.
section: Writing
order: 1
---

把这些字段视为站点的公开内容约定。

写作模式

布局已经会渲染页面标题和说明，所以正文可以直接从背景上下文开始，然后进入二级标题。

推荐结构：

  1. 用一到两段做开场和定调。
  2. 用 ## 承载主要叙述。
  3. 只有在页面真的需要时，才用 ### 拆出较短的子主题。

内部链接

优先使用类似 概览 或 快速开始 这样的站内路由链接，这样即使内容继续增长，站点也依然容易导航。

Markdown 也很适合放这些元素：

  • 对比表格
  • 命令和代码片段的围栏代码块
  • 用于重复性流程的简短有序列表

什么时候该让 React 进场

尽量把大多数内容保留在 Markdown 中。只有在页面需要布局逻辑、元数据聚合，或者一个放置得很克制的交互组件时，再引入 React。这样发布体验会更平静，而不会把每次内容修改都变成组件开发。