格式手册

格式手册

本页规定 AI-PM 的 Markdown 写作规范，请在编写内容时遵守。

文章结构

每篇文章以 YAML frontmatter 开头。无元信息时，空 frontmatter 写两行 ---：

---
---

新增页面应含一句 description: 页面描述（硬性要求），在中间写入键值：

---
description: 一句话描述页面内容
---

要求：一句 70–120 字、从正文首段提炼、含本页核心关键词（如「货币」「会计分录」「复利」），说明本页讲什么、学完能获得什么。缺省时全站摘要雷同、CTR 不可控；栏目导航页等确有需要时可豁免。

标题层级

文章标题使用 ##（# 留给站点标题）
小节使用 ###，子小节使用 ####
避免跳级（如 ## 后直接 ####）

文本格式

加粗：强调关键概念，如 RAG、Agent
行内代码：代码、命令、参数名
代码块：指明语言，如 ```python
中文使用全角标点，英文与数字使用半角
中文与英文/数字之间留一个空格

文风

一段一主题，关键句独立成段
条目倒装：术语：定义，细节拆为嵌套列表展开
删"一句话定位""值得注意的是"等元标签，让句子自己作定位
直接陈述，避免"不是 A，而是 B"的迂回框架
删条件句、括注旁注与站内交叉辨析，交叉信息交给链接
行为描述动词直给，不用"能"前缀
破折号只留真正同位语，解释性展开用冒号或句号
引号只用于引语、俗语、书名，普通术语不加引号
书中金句用 > 引用块，列表内嵌套写作 - > 引文
admonition 内每行一句，行间用空行分隔（单换行渲染会合并成一段）
表格单元格：短句、分号分隔、无"能"前缀、无引号
把读者当专业人士：不解释常识、不重复结论（「关键先建立框架」，不必再写「先搭体系再填内容」）
不打比方：论点靠事实与逻辑，俗语、成语少用
篇幅分配即优先级：核心写透、过程让位；具体例子只在该讲清楚时用
删引导腔：「先自查：你知道产品经理每天在做什么吗？」这类反问引导直接陈述
长句拆短，一逗到底要拆

图表与结构表达

多用 Mermaid：流程、分类、层级、关系、决策路径等结构，优先用 Mermaid 图表达，减少长段落和重复列表。
图文分工：图展示结构与路径，正文补充定义、判断标准、例外情况和操作细节；不要把完整段落塞进节点。
节点简洁：节点使用短语，单个节点只表达一个要点；复杂说明拆到图后的正文。
控制复杂度：统一阅读方向；节点过多、连线交叉或图幅过宽时拆成多张图。
保留文字线索：图后用一句话概括核心关系，确保读者不依赖图也能理解文章主旨。
代码块标注：使用 mermaid 代码块，并保持缩进清晰。

引用与标注

重要提醒使用 admonition：

???+ note "提示"
    这是提示内容。

常见类型：note、warning、tip、info、todo、example；不带标题的匿名块（??? 折叠 / !!! 展开）
引用外部资料时附上链接

链接

站内链接使用相对路径，如 [提示词工程](../ai/prompting.md)
站外链接直接给出完整 URL

文件与页面命名

页面文件与目录名一律使用 ASCII slug：小写英文（kebab-case），仅含 a-z、0-9、-，不用中文、大写、下划线或空格
示例：docs/ai/llm-inference.md、docs/business/05-corporate-finance/08-stock-valuation.md
系列课程目录保留数字前缀保证顺序（如 02-accounting），页面保留两位数字前缀（如 06-inventory）；index.md 固定
nav 显示标题保持中文，与文件路径解耦——只改路径，不改标题
新页面从创建起即遵循本规范；存量页面（business 区块 2026-08 已迁移）不得回退

图片

图片存放在文章同级的 images/ 子目录
文件命名：小写英文、下划线分隔，如 agent-flow.png
图片应有 alt 文本

列表

无序列表使用 -，有序列表使用 1.
- 注意：嵌套缩进用 4 个空格
条目保持简洁，一行为一个知识点

发现错误？想一起完善？在 GitHub 上编辑此页！
本页面贡献者：AI-PM Wiki Team
本页面的全部内容在 CC BY-SA 4.0 和 SATA 协议之条款下提供，附加条款亦可能应用