Markdown 转 HTML 最佳实践与教训

术-操作 · 术层 skill 全文

本页是 <code>rules/skills/bestpractice_markdown_html_conversion.md</code> 的逐字投影（仅隐私清洗，零改写）。

title: Markdown 转 HTML 最佳实践
category: BestPractice
tags: [markdown, html, pandoc, document-conversion]
difficulty: Easy
related_projects: []
created: 2025-02-12
updated: 2025-02-12

Markdown 转 HTML 最佳实践与教训

在将精心编写的 Markdown 文档转换为 HTML（特别是使用 Pandoc 等工具）时，我们总结了以下核心教训，以确保格式的准确性和专业性。

1. 列表格式的严格要求

必须留出空行

Markdown 转换器（如 Pandoc）通常需要列表（无序或有序列表）与其上方的段落之间有一个完整的空行。

• 错误做法：
• ```markdown
• 相语在婚恋中的应用：
• 强弱匹配
• 福气匹配
• ```
• 结果：列表可能被识别为普通文本，导致 HTML 中无法显示为点选符号。

• 正确做法：
• ```markdown
• 相语在婚恋中的应用：

• 强弱匹配
• 福气匹配
• ```

2. 章节合并的结构完整性

章节间的换行符

当合并多个 Markdown 文件为一个大文档时，必须在文件之间插入至少两个换行符（即一个空行）。

• 原因：如果前一个文件以文本结束，而下一个文件以 # 标题开始，且中间没有空行，解析器可能会将标题逻辑混淆。
• 最佳实践：在 cat 或脚本合并时显式添加 \n\n。

3. 标题与引言的逻辑重组

移除冗余标题

在电子书或长篇教程中，如果每个章节都有一个单独的 ## 引言 标题，会增加目录的负担且视觉上显得断裂。

• 改进建议：移除 ## 引言 字样，直接将引言文字紧跟在章标题（#）之后。这使得阅读体验更加流畅，更符合现代书籍排版。

4. 移动端适配的 CSS 细节

间距管理

确保 HTML 的 body 或主容器具有足够的 padding（建议 24px 或更多），防止文字在移动设备上紧贴屏幕边缘。

5. 符号与括号的规范化

标题纯净化

在最终汇总文档中，尽量移除标题（如 ## 【本章小结】）中的非必要中括号或特殊符号。使用简洁的 ## 本章小结 不仅视觉上更专业，也有利于自动生成的目录（TOC）显得整洁。