这是一篇示例文章,可替换为你的内容。
先组织问题,再选择语法
Markdown 的便利不在于符号少,而在于普通文本也能保留结构。写作时可以先用一句话说明文章要解决的问题,再按读者理解它的顺序展开。不必为了让页面显得丰富,给每个短段落都添加标题。
在已经使用文章标题作为一级标题的页面里,正文通常从二级标题开始。小节需要继续展开时再用三级标题,避免只为调整字号而跳过层级。标题描述内容,比“第一部分”“其他事项”更方便检索。
## 记录一次错误排查
先交代现象,再说明适用条件。
- 保留能够复现问题的输入
- 区分观察结果与原因判断
代码要带着边界出现
代码围栏标注语言,行内代码留给文件名、变量名和短表达式。示例应当尽量小,但上下文不能省得只剩结论。例如,统一文本换行符可以写成下面这样:
function normalizeLineEndings(text) {
return text.replace(/\r\n?/g, "\n");
}
console.log(normalizeLineEndings("first\r\nsecond"));
这段 JavaScript 接收字符串,将回车换行和单独的回车转换为换行符,不会合并连续空行,也不会删除行尾空格。把这些边界说明白,读者才知道是否适合放进自己的处理流程;不要把预期结果写成未经验证的运行记录。
让不同结构各司其职
| 内容关系 | 合适的写法 | 容易出现的问题 |
|---|---|---|
| 必须依次完成的步骤 | 有序列表 | 把先后关系藏在长段落里 |
| 可以独立查看的要点 | 无序列表 | 每项同时讨论几个主题 |
| 同一组维度的比较 | 表格 | 单元格太长,窄屏难读 |
| 需要特别辨认的原话 | 引用块 | 没有交代引语与正文的关系 |
表格适合横向比较,不适合承载整段推理。遇到需要解释来龙去脉的内容,回到自然段,往往比继续扩展表格更清楚。
格式的任务,是让读者少花力气辨认结构。
交给下一次编辑的自己
保存之前,可以从头检查一次:标题是否准确,列表是否并列,链接文字是否说明去向,图片是否有能表达信息的替代文本。描述变化时也要交代版本或日期,不让“现在”“最新版”成为很快过期的指代。
源文件中的段落保持适度长度,修改时更容易看出差异。真正值得坚持的不是某种排版洁癖,而是让下一次补充内容的人,仍能迅速读懂这篇文章为什么这样组织。
谢谢你读到这里。