Markdown 资料排版规范

Markdown 资料排版规范

2020 年 01 月 03 日 作者：能动少C71尤佳睿 3142 字 | 8 分钟

本页面从原有的「学研部排版路线」一篇中摘出，主要是对 Markdown 资料排版的若干要求、建议。

资料的内容很重要，但呈现的方式甚至更为重要。具体而言，这里所谓的「方式」应归结为两个层面：内容的组织结构，以及排版方式。

1 资料的组织结构

如果你正在编写一份资料，内容甚多，则你应该好好考虑资料的组织形式。例如，对同样一本书，这样的目录结构是较为清晰的：

  • 第一章 实数域与数列极限
    • 1.1 实数集的构造
      • 1.1.1 自然数集：Peano 公理
      • 1.1.2 整数集的构造
      • 1.1.3 有理数集的构造与性质
      • 1.1.4 实数集构造：分割方法
      • 1.1.5 实数集构造：完备数列方法
    • 1.2 实数公理体系
      • 1.2.1 Dedekind 公理与连续性公理
      • 1.2.2 确界定理与区间套定理
      • …
    • 1.3 数列及其极限
      • …
    • …
  • 第二章 函数极限理论
    • …
  • 第三章 连续函数理论
  • 第四章 一元微分学
  • …

相反地，以下这种目录则显然会使人「望而却步」：

  • 1 实数集的构造
    • 1-1 自然数集
    • 1-2 Peano 公理
  • 2 整数集与有理数集的构造
  • 3 实数集构造：分割方法
    • 3-1 另一种方法：完备数列方法
    • 3-2 实数公理体系简述
      • 3-2-1 第一类公理
        • 3-2-1-1 第一类公理的特征
        • …
  • 4 Dedekind 公理
    • 4-2 补充：连续性公理
  • …

作为资料的编写者，你应该在编写资料之前事先规划各部分内容的层次（以目录作为一个指导标准）。通常而言，这样几种做法值得推荐：

「挂靠」已有章节. 编写某些课程的辅导资料时，可以直接依靠课程、课本的章节划分组织内容。这是最常见的一种做法；在此情况下，二级标题基本已经够用，不需要再向下划分太多的层次。

简单分类. 对于特定内容而编写的资料，可以简单分几类，将它们作为资料的一级标题。例如，要从以上例子所涉及的数学知识中抽取「实数公理体系简述」为主题，编写一本小册子。那么，可以根据这些公理（总计 7 – 9 个）的一些特征，将其分为两类或三类，分别分析；再加上「两类公理的联系与区别」、「绪论」、「总结」等循规蹈矩的内容，一份言简意赅、层次清晰的资料就已经初步浮现了。

三级标题系统. 这是一般情况下适用的原则，包括：

  • 标题不要超过三层，不要跨级（例如，一级标题下直接附属三级标题——这在 Markdown 文档中常常出现）。
  • 各层上的内容范畴大致同级。
  • 每一部分的专属内容（例如，一个二级标题的专属内容指：在某一二级标题下方，而没有归属于任何一个三级标题的内容）不要太多，且尽量平衡。
  • 最低级标题的总数可稍多些，但更高级的标题尽可能少。
  • 相近的内容应合并，泛化的概念应放在高级标题之下。

以上所言的「一级标题」，不是指作品的名称、总标题，而是指目录下的第一级标题——通常所言的「章」。

以上这些原则，「玄之又玄」，十分抽象。只有以一个普通读者的身份反复品味、分析自己的作品，并适当征求他人的看法，你才能在内容的组织能力上有所进步。

2 Markdown 文档排版规范

在总体的组织结构之外，文档内部的种种细节也应非常注意。在互联网上，一些资料不仅「长得漂亮」（样式精巧），内容也很赏心悦目；一些资料虽然没有华丽的外表，却给人一种清新、整洁的感受——例如这个博客中的页面。后者所依靠的，就是排版上的精雕细琢。

作为资料的编写者，我们并不刻意追求排版的高质量；但是，我们应对资料的阅读者具有起码的尊重，不应拿模糊的公式截图来困扰读者，也不应该用随机分布的行间距、字间距、单词拼写和字体切换来降低读者的阅读效率。

为了提高学辅资料的排版质量，此处呼吁学研部的每一位资料编写者在工作过程中，尽力遵守以下几条基本的排版原则：

钱院学辅中文排版规范（第一版，2019 年 8 月 10日）
原则内容 示例
请使用直角引号。 ✔ 「这样」，「这样地『这样』」。
✘ “这样”，“这样地‘这样’”。
中文字符与西文、数字之间必须留有空格。 ✔ 我们学校的名称是 Xi'an Jiaotong University 或西安交通大学，创建于 1896 年。
✘ 我们学校的名称是Xi'an Jiaotong University或西安交通大学，创建于1896年。
中文半角符号与西文之间不留空格。 ✔ 西安交通大学，英文名为 Xi'an Jiaotong University，是一所坐落在西安市（Xi'an）的综合性大学。
✘ 西安交通大学，英文名为 Xi'an Jiaotong University ，是一所坐落在西安市（ Xi'an ）的综合性大学。
除非是纯西文的短语、句子、段落、文档，均采用中文的标点符号（Markdown 所需的标记符号当然除外）。 ✔ Notes：普通话（Mandarin）是一种非常棒的语言，真的！
✘ Notes: 普通话 (Mandarin) 是一种非常棒的语言, 真的!
✔ 你可以参见《Legendary: Guides to Mandarin & Cantonese》。
✘ 你可以参见《Legendary：Guides to Mandarin＆Cantonese》。
在遵守以上原则的前提下，链接文本与其他文本之间不留空格。 ✔ 你可以参考开源中国或 GitHub 首页给出的说明。
✘ 你可以参考 开源中国 或GitHub 首页给出的说明。
在遵守以上原则的前提下，对于带字母单位的数字，值与单位之间不留空格。 ✔ 今天的天气为「中雨」，最高气温为 26℃，城区降水量可达 15mm 以上。
✘ 今天的天气为「中雨」，最高气温为 26 ℃，城区降水量可达 15 mm 以上。

对以上内容的补充说明：

  • 关于第一条引号的用法，需要强调的是：选择直角引号而非横排引号，并非由于谁优谁劣，而是想推动你在学研部的工作中尝试一种新的方式。你可能需要参考：知乎 - 如何输入直角引号（「」和『』 ）？
  • 关于空格，需要注意的是：在 LaTeX、Word 等排版系统中，中文与英文、半角数字之间的间距往往能够自动生成。编写者应根据资料的最终形式决定是否需要手动加空格。

在没有出现新的问题之前，这份规范将维持现状。

参与讨论