# 降价 Markdown 文件的格式和结构约定。基于 CommonMark 规范、GitHub Flavored Markdown (GFM) 扩展、Google Markdown 样式指南和 markdownlint 默认值。 ## 1\.一致性选择这些是任意的，但必须在文件内和项目之间保持一致：元素|大会 |基本原理 ---|---|--- 标题 | ATX (`#`) |一致，易于 grep 无序列表 |连字符 (`-`) |通过强调避免“*”歧义有序列表 |惰性编号（全部为“1.”）|重新排序时差异保持干净强调|星号（`*斜体*`、`**粗体**`）|比下划线更常见代码围栏|反引号 (``````) |标准，而不是波形符水平规则 | `---` |三个连字符，没有其他链接样式|内联用于短/一次性，参考用于长/重复 |平衡可读性和可维护性 ## 2\.标题 ### 结构 * 每个文件一个“#”(H1) — 文档标题 * 恰好增加一级——永远不要从`##`跳到`####` * 每个标题前后有空行 * 不要以标点符号结束标题（没有尾随“.”、“:”、“?”） * 不要在标题内使用强调（`**`、`*`、```）——标题本身提供强调 * 标题文本在文档中必须是唯一的 - 实现可靠的片段链接 ###案例 * 标题句首字母大写：仅第一个单词和专有名词大写 * 例外：H1 文档标题可以接受标题大小写 ### 示例 # 用户认证 ## 代币生命周期 ### 刷新令牌轮换 ### 反模式 # 用户认证 ## 令牌生命周期： #### 深标题 ## **重要**部分 ## 3\.列表 ### 标记 * 无序：`-`（连字符），在整个文件中一致 * 有序：每个项目的“1.”（惰性编号）——渲染器自动编号，差异保持干净 * 列表中第一项之前和最后一项之后的空行 * 紧密列表中的项目之间没有空行（同一逻辑组） * 仅当项目包含多个段落或块时，项目之间才有空行 ### 内容 * 单句项目：无尾随句号 * 多句子项目：在所有句子上使用句号 * 缩进连续行以与项目文本的第一个字符对齐（“-”为 2 个空格，“1.”为 3 个空格） ### 嵌套 * 缩进嵌套列表以与父项文本对齐 * 最多 3 层嵌套——更深的嵌套表明内容应该重组 ### 示例 - 第一项 - 第二个项目有更长的描述换行到下一行 - 第三项 1. 第一步 1. 第二步 1. 第三步 ## 4\.表格 ### 格式化 * 每个表格前后有空行 * 使用前导和尾随管道：`|细胞|细胞|` * 垂直对齐管道以提高源代码的可读性（规范不要求，但有助于审查） * 每行的列数相同——没有参差不齐的表格 * 标题分隔符使用“---”（每列至少三个连字符），管道周围有空格：“|” --- | --- |` ### 内容 * 保持单元格简洁——如果单元格需要段落，则数据不属于表格 * 当数据不是真正的二维时更喜欢列表 * 显示标识符、命令或路径时在单元格中使用代码格式 * 没有空表——如果只有一列，请使用列表 ### 对齐 * 默认值：左对齐（分隔符中不需要冒号） * 右对齐数字：分隔符中的“---:” * 谨慎使用对齐方式——大多数内容左对齐读起来很好 ### 示例 |命令 |描述 | | --- | --- | | `只需检查一下` |运行 linter 和类型检查 | | `只是测试` |运行所有测试 | ## 5\.代码块 ### 击剑 * 始终使用隔离代码块（三个反引号）——切勿缩进代码块 * 始终在打开反引号后声明语言：````rust`、````sql`、````markdown` * 使用“text”或“console”进行纯输出，没有语法突出显示 * 每个代码块前后都有空行 ### 外壳示例 * 不要在命令前加上 `$` 前缀，除非显示交错的命令和输出 * 显示命令+输出时，仅在命令行中使用“$”前缀 * 使用`sh`或`bash`作为shell命令的语言标识符 ### 内容 * 保持示例最少——显示相关模式，而不是完整文件 * 谨慎使用注释——周围的散文应该解释这个例子 * 清楚地标记不正确的模式：`// WRONG`、`// CORRECT`、``、`` ### 示例 ``生锈 // 正确——聚合前过滤让总计：BigDecimal = 项目 .iter() .filter(|i| i.currency == "美元") .sum(); ```` ## 6\.友情链接 ### 链接文本 * 断章取义的描述性文字——切勿“单击此处”、“此处”、“此”、“链接” * 屏幕阅读器通过链接文本导航 - 通用标签无法访问 * 保持链接文本简洁但有意义：通常为 2-6 个单词 ### 内联与参考 * 内联“[text](url)”，用于使用一次的短 URL * 参考样式“[text][ref]”，底部带有“[ref]: url”，用于长或重复的 URL * 在文件末尾或节末尾对引用定义进行分组 ### URL 约定 * 所有外部链接均使用 HTTPS * 片段链接 (`#heading-text`) 必须引用文档中的有效标题 * 同一存储库内链接的相对路径 * 验证重命名或移动文件后链接是否仍然解析 ### 示例有关详细信息，请参阅 [CommonMark 规范](https://spec.commonmark.org/)。 [API 设计指南][api-guide] 涵盖了分页模式。 [api 指南]：https://cloud.google.com/apis/design/design_patterns#list_pagination ## 7\.空白 ### 行结尾 * 任何行上都没有尾随空格 * 无硬制表符 — 使用空格进行缩进 * 文件以一个换行符结束（EOF 处没有空行，没有丢失换行符） ### 空行 * 不同类型的块之间有一个空行（标题、段落、列表、代码、表格） * 没有多个连续的空行——只有一个空行作为分隔符 * 前后空行：标题、代码块、表格、水平线、列表 ### 线长度 * 散文没有严格的行长限制——让编辑换行 * 例外：代码块应保持在 100 个字符以下，以便终端和差异中的可读性 * 表：将行保持在一行上 - 水平滚动优于换行的表行 ## 8\.反模式常见错误快速参考表：反模式|问题 |修复 ---|---|--- 混合列表标记（`-` 和 `*`）|不一致、令人困惑的差异 |选择其中之一，全程使用跳过标题级别 |破碎的轮廓层次结构|加一缩进代码块 |脆弱，无语言提示|使用围栏块裸网址 |交通不便 |用“[描述性文本](url)”换行用空格强调 (`* 文本 *`) |不会渲染为强调 |删除空格：`*text*` 通用链接文本（“单击此处”）|无法访问，链接列表中无意义 |描述目的地内联 HTML（`
`、``）|破坏可移植性，更难维护 |使用 Markdown 等效项标题中的尾随标点符号 |吵闹、不一致 |删除`.`、`:`、`?` 多个H1 |文档标题不明确 |顶部有一个 H1 代码围栏上没有语言 |没有语法高亮 |始终声明语言多个连续空行 |源中的视觉噪声 |正好一个空行硬标签|渲染不一致 |仅限空格

降价

包含技能