用 Markdown 与模板分离内容和排版

写一份长期维护的技术文档时，内容和样式经常一起变化。新增一个章节后，标题编号、目录和图表位置都要重新调整；换一种输出格式，又需要重复排版。

一种常见办法，是用 Markdown 保存正文结构，再交给模板和构建工具决定最终外观。

正文表达含义

标题、段落、列表和代码块应说明内容的关系，而不是模拟屏幕上的位置。例如，使用二级标题表示章节，不要仅仅把一行文字加粗并调大字号。

## 读取配置

程序启动时先检查配置，再开始处理输入。

1. 读取配置文件。
2. 检查必要字段。
3. 记录生效参数。

这样的文本容易阅读，也能被转换工具识别为章节和有序步骤。需要改变标题颜色或段间距时，可以修改统一样式，不必逐段调整正文。

标题、摘要和日期等信息，可以放在文档开头的元数据区。不同工具对元数据的解释可能不同，文件需要遵循当前构建工具的格式约定。

---
title: "一个小工具的使用说明"
date: 2026-11-05
description: "从安装到首次运行的基本步骤。"
---

模板可以把这些信息放到页面标题或目录中。若文档不需要公开作者身份，就不必加入个人姓名、邮箱或单位。示例元数据也应在发布前检查，避免把模板作者的信息误当成自己的内容发布。

同一份 Markdown 可以生成网页，也可以通过文档转换工具输出 PDF。但两种格式的版面条件不同：网页允许连续滚动，PDF 则有固定纸张、页边距和分页。

长代码行、宽表格和公式通常最容易出现差异。可以先准备一个很小的检查文档，包含中文标题、列表、链接、代码块和表格，再分别生成目标格式。发现字体缺字或内容溢出时，优先在模板中调整通用规则。

Markdown 也有不同方言。脚注、公式和特殊引用语法未必被所有工具支持，选择这些功能时应确认目标转换链能够处理。

一个可以长期维护的模板项目，最好同时记录构建命令、所需工具和资源位置。正文、模板和资源可按职责存放：

document/
  content.md
  template/
  assets/
  README.md

图片和字体除了要能找到，还需要确认使用许可。对外发布时，只收集最终需要的资源，避免把草稿、构建日志和带有本地路径的中间文件一起上传。

内容与样式分离不会消除全部排版工作，但能让修改更集中：正文负责表达，模板负责呈现，构建说明负责把两者可靠地连接起来。