Markdown style guide

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

摘要

文档提供了Markdown编写规范的详细指南，强调了简单性、可读性和可维护性。主要内容包括文档布局、标题使用、列表格式、代码块嵌入、链接处理、图片使用以及避免HTML的建议。文档推荐使用ATX风格标题，避免冗长的表格，优先使用列表和Markdown语法，以提高文档的可读性和可编辑性。

AI总结

《Markdown Style Guide》总结如下：

1. **核心目标**
Markdown风格指南旨在平衡三项目标：源文本可读性、文件可维护性以及语法简洁易记性。通过简洁一致的风格，提升文档的可读性和协作性。

2. **文档布局**
- 文档标题应为Level 1标题，建议与文件名一致。
- 简短介绍后可添加[TOC]生成目录。
- 主内容从Level 2标题开始，避免使用冗长的标题层级。

3. **标题规范**
- 使用ATX风格标题（`#`），避免使用下划线（`=`或`-`）。
- 在标题前后留出空行，提升可读性。

4. **列表建议**
- 长列表使用惰性编号（如`1.`），减少维护难度。
- 列表前后留空行，避免嵌套混乱。

5. **代码规范**
- 短代码使用内联代码（`backticks`），长代码使用代码块。
- 明确代码块语言，便于语法高亮和编辑。
- 命令行示例需使用转义符（`\`）避免换行，保持可复制性。

6. **链接与图片**
- 链接使用有意义的标题，避免“点击此处”等无意义文本。
- 少用图片，优先使用文字描述。
- 长链接需缩短，避免破坏排版。

7. **表格与HTML**
- 表格尽量简洁，避免复杂嵌套，优先使用列表。
- 尽量避免使用HTML，优先使用Markdown语法，提升可读性和可维护性。

8. **其他注意事项**
- 避免尾随空格，使用反斜杠强制换行。
- 遵守字符限制（如80字符），长文本需换行。
- 使用自然语言表达，避免生硬格式。

总结：通过遵循这些规范，可以写出简洁、易读、可维护的Markdown文档，提升协作效率和阅读体验。