Markdown Article Rules

Scope

• 以下规则用于新增或修改 src/**/*.md 下的 Markdown 文章。
• src/public/** 下的静态资源不适用。
• 首页、导航页、专题页等特殊页面，可按既有结构处理，不强行套用完整文章模板。

标题规则

• 全文仅保留一个一级标题 # 作为文章标题。
• 一级标题应简短，优先控制在 15 个字以内；涉及产品名、配置项、专有术语时可适度放宽。
• 正文内容从二级标题 ## 开始组织，并按层级递进展开。
• 标题不要手写序号，例如“第一章”或“1.”。
• 标题层级不要跳级，避免 ## 后直接接 ####。

强调规则

• 常见的有序列表、无序列表项默认不要整体加粗。
• 加粗仅用于少量关键术语或确实需要特别提醒的内容。

行内代码规则

• 以下内容使用反引号包裹：文件名、目录名、路径、类名、函数名、变量名、命令行命令、配置项、API 路径、包名、模块名、简短代码片段。
• 产品名、技术名词、协议名和概念术语，只有在被当作具体标识符、配置项、命令、路径或代码片段引用时，才使用反引号。
• 同一篇文章中，同一类对象的写法应保持一致，不要同一处加反引号、另一处又不用。

代码块规则

• 使用三个反引号包裹代码块，并尽量标明语言类型。
• 代码块前后各保留一个空行。
• 如需给示例代码添加注释，优先使用中文。
• 代码示例应尽量简短，并直接服务于正文说明。
• 命令行示例优先使用 sh 代码块，内容尽量可以直接复制执行。

列表与空行规则

• 列表使用无序列表 - 或有序列表 1.。
• 列表前后各保留一个空行。
• 段落之间保留一个空行。
• 标题后保留一个空行再写内容。

内容组织规则

• 文章通常包含：Frontmatter、标题、概述、主要内容、参考链接。
• 正文开头保留一个简短的介绍性小节，推荐使用 ## 概述。
• 开头介绍性小节控制在 1 到 2 段，先讲主题、背景和阅读收益，再进入正文。
• 不要求专门写“总结”章节，可按主题和篇幅决定是否收束全文。
• 优先按“先讲结论，再讲原理，再给示例”的顺序组织内容。

Frontmatter 规则

• 文章开头优先使用 YAML frontmatter。
• frontmatter 放在文件最开头，使用 --- 包裹。
• title 应与正文唯一一级标题 # 保持一致或高度一致。
• 文章型内容默认必须编写 frontmatter，不再省略。
• 普通文章至少包含以下字段：title、description、keywords、group、groupOrder、order、draft。
• keywords 使用数组，填写 3 到 8 个与正文强相关的关键词。
• description 要用自然语言说明文章主题、背景和主要收益，不要写成关键词列表。
• title 要具体，不要只写“笔记”“总结”“问题记录”这类泛化标题。
• lang 与 head 属于站点文章的常用字段；新增文章默认应补齐，除非该目录下既有文章明确不使用。
• head 中的 og:title、og:description 应与 title、description 含义一致。
• 修改现有文章时，不要随意删除与站点结构相关的既有 frontmatter 字段。
• 首页、导航页、专题页等特殊页面，可按既有文件约定省略 group、groupOrder、order 等字段。

参考链接规则

• 如需补充参考资料，统一放在文末，使用二级标题 ## 参考。

表达风格规则

• 文章开头的介绍保持简洁，只保留一个介绍性小节。
• 文章结尾不要写“xx 建议”“新手注意 xx”之类的收尾。
• 正文说明、示例解释、代码注释优先使用中文表达。
• 优先把概念、结论和适用场景讲清楚，再补充原理和细节。
• 表达应自然、清楚，避免过度口语化或堆砌术语。
• 示例应直接服务于正文内容，不写与主题关系不大的演示代码或命令。

正向风格规则

• 语言风格以简洁、直接、清楚为主，像有经验的技术作者在写稿，而不是在做客服式引导。
• 段落尽量短，优先一段讲清一个意思；能用两句说完，就不要拖成五句。
• 先写事实、结论或判断，再补原因、边界和例子，不绕远路。
• 多用具体名词和具体动作，例如文件、命令、配置项、报错、限制条件，少用空泛抽象词。
• 允许带一点轻微幽默，但应克制，像点到为止的旁白，不要写成段子、梗文或夸张口吻。
• 幽默优先用于缓解说明的生硬感，例如简短插句、轻微自嘲、反差提醒；不要影响事实表达和技术准确性。
• 优先写“人会怎么遇到这个问题、实际应该怎么处理”，少写模板化的铺垫和宏大叙事。
• 适当保留作者判断，但判断后面要跟依据、场景或限制，不写只有态度没有信息的句子。
• 说明复杂概念时，优先先给一个准确说法，再补一个贴切但克制的比喻；比喻只能帮助理解，不能代替定义。
• 转场要自然，尽量靠信息推进，而不是靠“换句话说”“接下来我们来看看”这类提示语撑结构。
• 标题应对应正文里的真实信息块，标题下要有实际内容，不写只有气氛、没有信息的标题。
• 能落到真实使用场景时，优先落到具体场景，例如安装、配置、排错、接入、限制，而不是泛泛而谈。
• 如果正文已经说清楚，就直接结束，不额外补一段“总的来说”“最后”“一句话总结”。
• 默认把文章写成“可直接发布”的成稿，而不是聊天回答的整理版。

去 AI 味规则

• 避免把文章写成固定模板，不要默认套用“很多人第一次……”“这篇文章只做一件事……”“先给结论……”“最后的判断……”这类开头和结尾。
• 避免高频使用“不是……而是……”“不只是……还……”“真正……不是……”这类对照句式；一篇文章中同类句式不宜反复出现。
• 避免过度使用“如果你……”“你会发现……”“换句话说……”“最值得……”“最关键……”“核心价值……”这类提示性口头语。
• 第二人称 你 只在操作步骤、前提条件、风险提醒中使用；概念解释和事实说明优先使用客观陈述。
• 开头小节不要空转，不要先讲写作意图、阅读收益或泛泛感受；前两段就应进入主题对象、场景或核心问题。
• 结尾不要为了“收束”而重复前文，不要写空泛总结；如果没有新增信息，正文结束后直接进入 ## 参考。
• 少写“一个适合起步的……”“最值得记住的……”“这套系列文章会讲什么……”这类弱信息密度标题，优先使用和正文事实直接对应的标题。
• 优先使用具体对象和具体信息：文件名、命令、配置项、目录、场景、限制条件、前提版本。少写抽象评价和泛化判断。
• 段落应短而实，不要连续多段都以相同句式起手；相邻段落应避免重复使用“如果……”“对于……”“很多人……”“通常……”。
• 表达应像有明确编辑目的的技术作者，而不是在对读者“陪聊”或“带路”；少做情绪铺垫，多给事实、边界和例子。
• 不要为了显得完整而强行补“概念层、能力层、工作流层”这类整齐分层；只有在确实帮助理解时才分层。
• 不要滥用“更像”“可以理解成”“可以把它看成”，一篇文章中这类比喻性转述应控制次数，且必须比原说法更易懂。

其他规则

• 图片使用标准 Markdown 语法 ![alt](url)。
• 链接使用标准 Markdown 语法 [text](url)。
• 正文使用中文标点符号。
• 可少量使用 emoji 调节语气或做轻提示，但应克制。
• emoji 不用于标题，不用于列表符号，不用于严肃的风险、限制和结论表达。
• 一篇文章默认控制在 0 到 3 个 emoji，且应自然分布，不要集中堆叠。