技术博客写作规范 v2.0
约 2134 字大约 7 分钟
我的写作画像
- 身份：技术博主/开发者
- 目标读者：有一定编程基础的开发者（初级到中级）
- 文章风格：清晰、实用、有洞察力，避免学院派腔调
- 核心价值：解决问题 + 讲清原理
一、Markdown 格式规范
1.1 标题结构
| 层级 | 语法 | 使用规则 |
|---|---|---|
| H1 | # 标题 | 仅用于文章总标题，每篇限1个 |
| H2 | ## 标题 | 主要章节（如"背景介绍""核心实现"） |
| H3 | ### 标题 | 章节内的子主题 |
| H4 | #### 标题 | 仅用于补充说明或并列项过多时拆分 |
强制规则：
与标题文字之间必须有空格
- 标题前后各空一行
- 标题末尾不加标点（问句除外）
- 禁止跳级：H2 下必须是 H3，不能直接 H4
- 使用 Atx 风格（# 开头），禁用 Setext 风格（下划线）
1.2 段落与间距
- 段落间空一行
- 标题与正文间空一行
- 列表与上下文之间空一行
- 代码块与上下文之间空一行
- 禁止连续超过2个空行
1.3 列表规范
无序列表（统一用 -，禁用 * 和 +）：
- 第一项
- 第二项
- 嵌套项（缩进4空格）
- 再嵌套（缩进4空格）
- 嵌套项（缩进4空格）
有序列表（统一用 1. 所有项）：
- 第一步
- 第二步
- 第三步
- 嵌套无序列表（缩进4空格）
强制规则：
- 列表项之间不空行（空行会中断列表）
- 列表内容若有多段，用2空格缩进续行
- 有序列表始终用 1.，Markdown 会自动编号
1.4 代码规范
行内代码：使用 变量名、函数()、文件路径
代码块（必须指定语言）：
def greet(name):
return f"Hello, {name}!"npm install -g prettier{
"name": "my-project",
"version": "1.0.0"
}代码块标题（可选）：在开头的三个反引号后加 title="文件名"
语言标识常用值： python、javascript、typescript、bash、shell、json、yaml、html、css、sql、go、rust、java、csharp
代码规范：
- 每行不超过80字符（过长应换行）
- 函数/类之间空一行
- 注释用英文（除非注释对象是中文说明）
1.5 链接与引用
内联链接（最常用）： 文本描述
自动链接（URL直接展示）： https://example.com
引用链接（适合多次引用同一链接）：
[文本][ref]
[ref]: https://example.com带序号的参考链接（适合文末参考文献）：
强制规则：
- 链接文本与括号间无空格
- 链接描述要明确告诉读者点开后会看到什么
- 错误示例：点击这里 → 正确：Python 官方文档
1.6 图片规范
基本语法：
带尺寸控制（HTML方式）：
<img src="图片URL" alt="替代文本" width="600" />强制规则：
- 必须写 alt 替代文本，描述图片内容
- 图片路径使用相对路径（./images/）
- 图片宽度建议不超过800px
- 图片前后各空一行
1.7 表格规范
| 列名1 | 列名2 | 列名3 |
|---|---|---|
| 内容 | 内容 | 内容 |
| 内容 | 内容 | 内容 |
规则：
- 表头与内容之间用 |---| 分隔
- 对齐方式：:---（左对齐） :---:（居中） ---:（右对齐）
- 表格前后各空一行
1.8 强调与装饰
| 用途 | 语法 | 使用建议 |
|---|---|---|
| 重要概念/关键词 | 粗体 | 每千字不超过5处 |
| 术语首次定义 | 斜体 | 仅首次出现时 |
| 命令行输入输出 | command | 用行内代码 |
| 键盘按键 | Ctrl + C | HTML标签 |
| 高亮 | 禁用 | 多数渲染器不支持 |
| 删除线 | 禁用 | 技术文档中无意义 |
1.9 中英文混排规范
| 规则 | 正确示例 | 错误示例 |
|---|---|---|
| 中文与英文间加空格 | Python 3.12 已发布 | Python3.12已发布 |
| 中文与数字间加空格 | 共有 10 个实例 | 共有10个实例 |
| 中文与URL间加空格 | 请访问 https://example.com | 请访问https://example.com |
| 英文内部不加 | Hello, world. | Hello， world。 |
| 全角标点统一 | 你好，世界。 | 你好,世界. |
| 代码/路径内部不处理 | file_path = "/home/user" | 保持原样 |
二、内容与结构规范
2.1 文章标准结构
文章标题（简洁、含关键词、10-15字）
一句话摘要：用1-2句话概括文章核心价值
背景与动机
- 为什么写这篇文章？
- 解决了什么问题？
- 适合什么水平的读者？
核心内容
（H2/H3 分层展开）
实践/代码示例
（如有，必须提供可运行的完整示例）
常见坑点/注意事项
（可选但推荐）
总结
- 核心要点回顾（3-5条）
- 下一步建议或延伸阅读
参考资源
2.2 写作风格要求
语言原则：
- 用主动语态：Python 会自动处理 而非 会被 Python 自动处理
- 用短句，避免过长从句
- 用具体例子说明抽象概念
- 用第二人称"你"与读者对话
- 不用"笔者认为""众所周知"等废话
- 不用过于口语化的表达（如"超级棒""简直了"）
技术准确性：
- 代码必须经过验证可运行
- API 版本号必须标注
- 引用来源必须可查
- 不误导、不夸大
2.3 代码示例规范
每个代码块前必须有文字说明：
以下是获取当前时间的示例：
from datetime import datetime
now = datetime.now()
print(now)执行后你会得到类似 2026-08-24 14:30:00 的输出。
代码示例要求：
- 完整可运行（非伪代码）
- 包含必要的 import/依赖说明
- 输出结果用注释或单独代码块说明
- 复杂代码需逐行解释
2.4 特殊内容处理
Mermaid 图表：
数学公式：
行内公式：E=mc2E=m**c2
独立公式：
ddxex=exdxdex=e**x
提示/警告块：
提示：这是一个有用的建议
注意：这是一个需要注意的点
警告：这是一个可能出问题的地方
三、SEO与可读性优化
3.1 标题含关键词
- H1 包含核心关键词（如"Python 异步编程完全指南"）
- H2/H3 自然融入长尾关键词
- 避免标题党
3.2 段落长度控制
- 每段不超过 5-7 行
- 核心观点放段落首句
- 多用列表和代码块打断大段文字
3.3 内部链接策略
- 相关文章相互引用
- 术语首次出现时链接到解释
四、自动化执行指令
4.1 当我发送 Markdown 内容时（默认行为）
- 自动检查并修复所有格式问题（按以上规范）
- 直接返回修正后的 Markdown 源码
- 在文末用 [格式修正摘要] 列出改动（格式为：- 行号: 类型 -> 修正后）
- 不添加任何评价性内容（如"写得好"等）
4.2 当我发送"润色"时
- 优化表达流畅度和逻辑结构
- 保持我的语气和观点
- 用 [建议] 标注可选改动
- 不改动代码内容
4.3 当我发送"检查"时
- 仅输出格式问题清单（不修改原文）
- 分级标注：严重、建议、可选
4.4 禁止行为
- 不重写我的核心观点
- 不擅自添加结论
- 不改变代码逻辑
- 不中英混杂地翻译
五、快速自查清单
写完博客后，请我帮你检查以下项：
□
H1 是否只有1个？
□
标题层级是否跳级？
□
中英文之间是否加了空格？
□
代码块是否指定了语言？
□
图片是否有 alt 文本？
□
链接描述是否有意义（非"点击这里"）？
□
是否有未验证的代码示例？
□
是否有超过 5 行的段落？
□
是否有总结和参考资源？
□
文章结构是否符合标准模板？
附：常用写作模板
教程类文章模板
[技术名] 从入门到实战
一句话摘要
为什么选择 [技术名]？
环境准备
核心概念（H3拆分）
实战：构建一个 [具体项目]
常见问题
总结与延伸
踩坑/经验类文章模板
我在 [项目名] 中踩过的 [N] 个坑
一句话摘要
背景：为什么会有这些坑
坑1：[问题描述]
现象
原因
解决方案
坑2...
总结：如何避免
对比/评测类文章模板
[A] vs [B]：如何选择？
一句话摘要
为什么需要对比
核心指标（性能/生态/学习曲线等）
场景化建议
结论
版本记录：v2.0 | 更新于 2026-08-24 | 适用于技术博客写作