Markdown style guide

• 语言: 英语
• 格式: .pdf
• 来源: github.com/fgaray

摘要

本文档详细阐述了Markdown的使用规范和风格指南，旨在提升文档的可读性、可维护性和一致性。主要涵盖了文档布局、标题格式、列表使用、代码块声明、链接截取等方面。建议保持源文本简洁，避免使用复杂格式和HTML代码，优先使用列表而非表格，链接和图片使用应简洁明了。同时强调了代码块的语言声明和新行转义的重要性，以确保文档的易读性和便携性。

AI总结

以下是对《Markdown style guide》的中文总结：

---

# 《Markdown风格指南》总结

## 核心目标
1. 保持源文本可读且便携。
2. 确保Markdown文件在时间和团队中可维护。
3. 使用简单、易于记忆的语法。

---

## 文档布局
1. 通用布局建议：
- # 文档标题：首行使用一级标题，标题应与文件名一致。
- 简短介绍：1-3句话概述主题。
- [TOC]：在支持目录的平台上添加目录。
- ## 主题：后续内容使用二级标题开始。
- ## 参见：底部添加相关链接。

2. 免责声明：
- 作者信息可选，通常放在标题下方。
- 使用TOC后，确保目录更新。

---

## 格式规范
### 1. 字符行限制
- 遵循项目字符行限制，避免长URL或表格破坏限制。
- 尽量换行或在长链接前换行，保持可读性。

### 2. 空格与换行
- 避免行尾空格。
- 两空格行尾会插入``，但最好避免使用，直接用换行分段。

### 3. 标题
- 使用ATX风格（`# Heading`），避免下划线风格。
- 标题之间加空行，增强源文本可读性。

### 4. 列表
- 长列表使用“惰性编号”，Markdown会自动渲染。
- 列表中嵌入代码时，使用四空格缩进以保持列表结构。

### 5. 代码
- 内联代码：使用反引号包裹短代码或字段名。
- 代码块：多行代码使用三反引号包裹，显式声明语言。
- 逃逸换行：在终端代码中使用反斜杠 `\` 换行。

### 6. 链接
- 使用信息性标题，避免“link”或“here”。
- 长链接保持可读性，尽量避免超长URL。

### 7. 图片
- 稀疏使用图片，优选简单截图。
- 避免过多装饰性图片，保持文档简洁。

### 8. 表格
- 尽量使用列表代替表格，表格应简短。
- 复杂表格难以维护且阅读困难。

### 9. HTML
- 几乎所有需求都可用Markdown满足。
- 避免使用HTML或JS，以保持源文本可读性和兼容性。

---

## 总结
本文档强调了Markdown的简洁性和可维护性，通过合理的格式和结构规范，确保文档在团队协作和长期维护中保持高效和一致。重点包括：
1. 使用标准Markdown语法，避免HTML。
2. 确保标题、列表、代码块和链接的清晰性和可读性。
3. 避免复杂表格和长链接，优先使用列表和简洁图片。
4. 遵循字符行限制，保持源文本整洁。

通过遵循这些指南，可以提高文档的可读性、可维护性和协作效率。