mkdocs-for-agent main page-writing-spec.md

页面写作规范

这页说明 mkdocs-net 内容页应该怎么写。重点是让页面既适合用户阅读，也适合 AI Agent 后续继续生成、拆分和维护。

系统会如何理解页面

AI Agent 在写内容页时，需要按当前实现理解这些行为：

  • 页面内容由 Markdig 渲染。
  • 页面支持常见 Markdown 能力，例如表格、任务列表、自动链接、Emoji、脚注。
  • fenced code block 会高亮显示。
  • Mermaid 代码块可以生成图表。
  • 页面会自动补 [TOC]，因此标题结构必须清晰。
  • 页面标题优先取 YAML 里的 title，没有时再回退到页面前部的一级标题。
  • 相对链接和相对图片路径会被重写成站内可访问地址。

Markdown Project Page 设计规范

mkdocs-net 的内容页不是通用官网页，而是以正文阅读为中心的 markdown project page。AI Agent 和人工维护时，都应把下面这些规则当成固定约束：

  • 页面默认是三栏结构： 左侧项目导航，中间正文，右侧本页目录。
  • 左右栏是固定阅读辅助区，不承担主滚动职责。
  • 只有中间正文区域允许纵向滚动。
  • 内容页不应再设计顶部 header 和底部 footer。
  • 左侧导航点击后，应通过 PJAX 仅刷新正文区及相关状态，不做整页跳转。
  • 右侧 TOC 只表达当前页结构，不承载项目导航。
  • 左侧导航表达项目结构，不承载正文内锚点目录。
  • 页面目标是“内容优先”，不要加入首页式横幅、营销区、页脚导航、装饰性大 Banner。

可以把这套布局理解为：

+----------------+---------------------------+----------------+
| 左导航 固定     | 中间正文 独立向下滚动      | 右 TOC 固定     |
+----------------+---------------------------+----------------+

标准页面结构

每篇页面建议保持下面的固定骨架：

  1. 可选的 YAML 头。
  2. 一个清晰的 H1。
  3. 一段 1 到 3 句的摘要。
  4. 按任务组织的 ## 小节。
  5. 页尾的“相关页面”区块。

推荐的小节名称：

  • ## 适用场景
  • ## 前置条件
  • ## 操作步骤
  • ## 配置示例
  • ## 验证结果
  • ## 常见问题
  • ## 相关页面

推荐模板

下面这个模板适合直接复用：

---
title: 页面标题
---

# 页面标题

用 1 到 3 句说明这页解决什么问题、适合谁看、读完后能完成什么。

## 适用场景

- 什么时候需要看这页
- 这页不解决什么问题

## 前置条件

- 需要准备的环境
- 需要的账号、权限或依赖

## 操作步骤

1. 第一步做什么。
2. 第二步做什么。
3. 第三步做什么。

## 配置示例

```bash
echo "replace me with a real command"
```

```json
{
  "key": "value"
}
```

## 验证结果

- 成功时应看到什么结果
- 失败时先检查哪些项目

## 相关页面

- [帮助中心首页](https://mkdocs.feinian.net:443/mkdocs-for-agent/README.md)
- [AI Agent 工作流](https://mkdocs.feinian.net:443/mkdocs-for-agent/agent-workflow.md)

链接与资源写法

推荐：

[AI Agent 工作流](https://mkdocs.feinian.net:443/mkdocs-for-agent/agent-workflow.md)

不推荐：

[页面写作规范](/page-writing-spec.md)
[帮助中心](https://example.com/help-docs)

说明：

  • 站内页面优先使用相对路径。
  • 图片也优先使用相对路径，并应指向真实存在的文件。
  • 只有确实需要跳出当前文档站时才使用外链。

写作风格要求

  • 先写用户能完成什么，再写背景。
  • 小节名尽量任务导向，不要含糊。
  • 示例命令要可复制。
  • 示例配置要尽量贴近真实结构。
  • 页面较长时，优先继续用 ### 做局部拆分。
  • 要依赖清晰标题层级配合右侧 TOC，不要把长文写成无层级长段落。
  • 不要在 Markdown 正文里自己模拟站点级顶部栏、底部栏或额外导航框架。
  • 不要把一页写成没有标题、没有摘要、没有入口的碎片。

不推荐写法

错误示例 1：没有一级标题

这是一段说明。

## 配置示例

问题：

  • 页面入口不清晰。
  • 自动目录和页面标题语义都会变差。

错误示例 2：只有背景，没有动作

# 页面写作规范

本系统历史很长，理念也很多。

问题：

  • 用户无法快速完成任务。
  • AI Agent 难以抽取步骤和可执行信息。

错误示例 3：虚构路径

[部署说明](./deployment/docker.md)

问题：

  • 如果路径不存在，链接就会失效。
  • 错误路径会在后续文档中被不断复制。

交付前检查

  • 是否有 H1。
  • 是否有简短摘要。
  • 是否按任务组织 ## 小节。
  • 是否符合三栏内容页约束：无头无尾、左导航固定、右 TOC 固定、中间正文独立滚动。
  • 是否优先使用相对路径。
  • 是否所有链接都真实存在。
  • 是否避免了占位内容。
  • 是否保证代码块和模板块语法完整。

相关页面