转载于公司技术委员会

Markdown

EWiki

https://ewiki.baijiashilian.com/

  • 内部链接、标题链接
1
2
3
4

[技术规范](./index.md)
[首页](../index.md)
[技术分享](../技术培训/技术分享计划&记录.md)
[Markdown](#markdown)

检查工具

https://github.com/lint-md/lint-md

中英文混排

漢學家稱這個空白字元為「盤古之白」，因為它劈開了全形字和半形字之間的混沌。另有研究顯示，打字的時候不喜歡在中文和英文之間加空格的人，感情路都走得很辛苦，有七成的比例會在 34 歲的時候跟自己不愛的人結婚，而其餘三成的人最後只能把遺產留給自己的貓。畢竟愛情跟書寫都需要適時地留白。

—— vinta/pangu.js

以下内容主要摘录自 中文技术文档写作风格指南 | PDF，并做了一些归纳、总结。

中英文混排时最突出的几个问题：

空白

空格：

  • 空格一律使用半角，禁止使用全角空格

  • 英文中：

    • 英文单词/数字之间、句子之间使用半角空格
    • 数字和单位之间要有空格，例如 7 kg、8 MB、10 GB，但 60°、37°C、1/4、100%、4′5″ 固定写法除外
    • 逗号、句号、问号、叹号、省略号等常规标点符号左侧没有空格、右侧使用半角空格
    • 各种引号、括号、书名号内侧没有空格、外侧使用半角空格
    • 连字符、简写单词中的单引号、表示或/除法/分数的斜线、上面单位用到的符号等两侧不使用空格
    • 段落开头和末尾不使用空格

  • 特别注意英文单词/数字，在与汉字相邻时中间必须使用半角空格，但与全角标点符号之间（无论前后）不使用空格

  • 中文字符（包括汉字和标点符号）之间禁止使用半角空格

  • Markdown

    • 除表示缩进、列表级别、代码块中固有空格、表格中的空格外，禁止连续出现两个及以上的半角空格，使用 <br /> 替代两个空格作为换行符（行尾两个空格的换行方式编辑时看不出来，容易出错）
    • 禁止使用 Tab（制表符）
    • 中文与中文链接之间是否有空格存在争议，这里建议统一使用空格（中英文之间按上面规范，也要有空格）
      • 链接与文字相邻处，如果没有标点符号则使用空格：
      • 链接与文字相邻处，如果有标点符号则不使用空格：
    • 粗体、斜体、删除线、高亮、inline 代码块等，规则与链接一样

换行：

  • 不同排版格式之间、段落之间建议使用一个空行隔开
  • 禁止连续出现两个及以上的空行
  • Markdown 末尾要有一个空行

标点符号

全角/半角选择：

  • 汉字标点符号基本都使用全角字符，起连接作用的短线、表示或/除法的斜线除外
  • 所有英文字母、阿拉伯数字、英文符号、英文标点符号、空格等均使用半角字符
  • 括号
    • 括号里全为英文/数字时使用半角括号，并在括号前后各空一个半角空格，括号和括号内的英文之间不需要空格
    • 括号里包含任何中文（无论是否包含英文、无论中文是否与括号相邻）时使用全角括号，括号前后不空格

严禁汉字和英文标点符号混排

常用中文标点符号：

  • 注意中文的 顿号 “、” 和逗号 “，” 的区别，英文没有顿号，使用逗号或句号

  • 连接号

    • “—”：一字线、全角、破折号的一半，表示序数起止、时间起止、空间起止或走向等，例如第 50—100 条、鲁迅（1881—1936）、2016—2020 年、北京—上海特快列车、秦岭—淮河线
    • “-”：短横线、半角、英文减号、两边不加空格，起连接作用，例如 2-1-201 室、图 2-1、表 3-4、2020-09-30、吐鲁番-哈密盆地
    • “～”：波浪线、全角，表示数值范围，例如 1 ～ 3 g、2 ～ 4 米、3 ～ 7 年内

  • 斜线

    • 表示除法，在中文语境不加空格，但对研发同学来说一般将其视为代码片段，代码中斜线两边需要加空格，如 120 / 60 = 2
    • 表示单位（除法的变形），两边不加空格，如 60 km/h
    • 表示“或”，两边不加空格，表示多个并列项建议使用顿号，例如他/她；你、我或他

  • 禁止连续多个的句号、问号和感叹号

大小写

  • 普通的单词和词组全小写，无论是否在开头，例如“argument label 和 parameter name 的区别是……”

  • 整个句子和英文原文保持一致，第一个单词的首字母要大写，例如乔布斯曾这样评价微软：“The only problem with Microsoft is they just have no taste. They have absolutely no taste.”

  • 专有名词保持固有样式，例如

    可以看官网或者 Wikipedia，如果一个名词出现在标题（标题使用全大写等特殊样式的除外）和正文中间位置（不是句子的第一个单词）时的样式相同，那么它就是专有形式

  • 缩写有多种形式，例如

    • 取每个单词首字母作为缩写的一般全部大写，例如 Software Development Kit 缩写为 SDK、Federal Bureau of Investigation 缩写为 FBI
    • 取前几个字母作为缩写的，大小写与正常单词一直，例如 Application 缩写为 App、applications 缩写为 apps
    • 把中间 N 个字母替换为数字的缩写，首尾字母与正常单词一致，例如 Internationalization 缩写为 I18n、localization 缩写为 l10n
    • 有些缩写有特殊的形式可视为专有名词，保持固有样式，例如 SaaS, PaaS, N/A, e.g., i.e.

  • 标题中主要单词首字母大写，例如 Type Safety and Type Inference

  • Markdown 的 code 中保持代码本身样式，例如 class、Int、propertyWrapper

code 不应过多使用，一般只有真正的代码才用，例如一般语句中的 class 可以直接翻译为“类”，只有在作为关键字使用时才需要用到 code，例如“使用 class 关键字定义类”

翻译

  • 一般中文中较为普及的单词要翻译成中文，例如 “When you define a function, you can …” 需要翻译成“定义函数时，可以……”

  • 新的、冷门的概念或容易引发歧义的单词建议不翻译，例如 “Each function parameter has both an argument label and a parameter name.” 可以翻译成“函数的每个参数都有一个 argument label 和一个 parameter name。”

  • 专有名词很普及的使用中文，不普及但有官方译名的可以使用中文名称，其它使用原文且使用正确的大小写形式，例如微软、苹果、戴姆勒 (Daimler)、GitHub、MySQL

参考

优秀范例

反面教材