文档库格式手册

本页面将列出在编写 OpenCloudOS 文档时需要注意的格式规范。请您在撰写或者修正文档内容之前仔细阅读本页面，以帮助您撰写更高质量的内容。

存储格式与文档链接

文件名以小写字母编写，单词中间以 - 分割。 例如：docs-format-guide.md。
英语文档在文件名后加 .en 。 例如：docs-format-guide.en.md。英语文档与中文文档存放于同一目录。
站内链接请使用相对路径，例如：[格式手册](docs-format-guide.md)、[常见问题](../faq.md)。
所有使用的图片均存储到仓库的 docs/assets 目录下且拥有有意义的文件名。图片的引用请使用相对路径，例如：![OpenCloudOS favicon](./assets/favicon.png)。

文档基本格式要求

除文章开头与文章名称统一的标题外，文章中不应出现 # 或者 <h1> 形式的一级标题。
标题的井号后应有一个英文半角空格。例如：## 二级标题。
标题后应有一个空行。
缩进使用 4 个空格，不要使用 Tab。
代码块、表格等块级元素前后应各有一个空行。
二级列表应在开头增加 4 个空格缩进。
同级列表之间的额外内容前后应各有一个空行，且增加 4 个空格缩进。
使用 ??? 或 !!! 开头的 Admonitions 语法时，每一行要包括在 Admonitions 语法的文本框的文本，开头必须有 4 个空格缩进。即使是空行，也必须保持与其他行一致的缩进。Admonitions 语法前后应各有一个空行，但内容前后不需要空行。
``` 样式的代码块应指定相关语言。例如：``` shell。如果代码内容为纯文本，则指定 text 作为语言。
中文文档撰写过程中应遵循本文结尾的中文文案排版指北。

提示

如果需要的话，请参考排版指北的工具部分使用相关工具帮助确保文案排版的正确性。

中文文案排版指北

提示

以下内容更改自 GitHub 用户 sparanoid 的《中文文案排版指北》，其内容使用 MIT 协议授权。原 GitHub 仓库

空格

「有研究显示，打字的时候不喜欢在中文和英文之间加空格的人，感情路都走得很辛苦，有七成的比例会在 34 岁的时候跟自己不爱的人结婚，而其余三成的人最后只能把遗产留给自己的猫。毕竟爱情跟书写都需要适时地留白。

与大家共勉之。」——vinta/paranoid-auto-spacing

中英文之间需要增加空格

正确：

目标是打造全面中立、开放、安全、稳定易用、高性能的 Linux 服务器操作系统

错误：

目标是打造全面中立、开放、安全、稳定易用、高性能的Linux服务器操作系统

目标是打造全面中立、开放、安全、稳定易用、高性能的 Linux服务器操作系统

完整的正确用法：

OpenCloudOS 是由 20 余家操作系统、云平台、软硬件厂商与个人共同倡议发起的操作系统社区项目，即将进入开放原子开源基金会（OpenAtom Foundation）孵化及运营。目标是打造全面中立、开放、安全、稳定易用、高性能的 Linux 服务器操作系统，共建国产操作系统开源技术社区，扩大社区发行版影响力，构建操作系统健康繁荣的生态。

中文与数字之间需要增加空格

正确：

OpenCloudOS 是由 20 余家操作系统、云平台、软硬件厂商与个人共同倡议发起的操作系统社区项目

错误：

OpenCloudOS 是由20余家操作系统、云平台、软硬件厂商与个人共同倡议发起的操作系统社区项目

数字与单位之间需要增加空格

正确：

使用 4k 扇区驱动器时，最大大小为 16 TiB。

错误：

使用 4k 扇区驱动器时，最大大小为 16TiB。

例外：度数／百分比与数字之间不需要增加空格：

正确：

角度为 90° 的角，就是直角。

新 MacBook Pro 有 15% 的 CPU 性能提升。

错误：

角度为 90 ° 的角，就是直角。

新 MacBook Pro 有 15 % 的 CPU 性能提升。

全角标点与其他字符之间不加空格

正确：

chrony 是网络时间协议（NTP）的通用实现。

错误：

chrony 是网络时间协议（ NTP ）的通用实现。

用 `text-spacing` 来挽救？

CSS Text Module Level 4 的 text-spacing 和 Microsoft 的 -ms-text-autospace 可以实现自动为中英文之间增加空白。不过目前并未普及，另外在其他应用场景，例如 macOS、iOS、Windows 等用户界面目前并不存在这个特性，所以请继续保持随手加空格的习惯。

标点符号

全角和半角

不明白什么是全角（全形）与半角（半形）符号？请查看维基百科条目『全角和半角』。

使用全角中文标点

正确：

chrony 是网络时间协议（NTP）的通用实现。

错误：

chrony 是网络时间协议 (NTP) 的通用实现。

chrony 是网络时间协议(NTP)的通用实现。

数字使用半角字符

正确：

使用 4k 扇区驱动器时，最大大小为 16 TiB。

错误：

使用４k 扇区驱动器时，最大大小为１６ TiB。

例外：在设计稿、宣传海报中如出现极少量数字的情形时，为方便文字对齐，是可以使用全角数字的。

遇到完整的英文整句、特殊名词，其内容使用半角标点

正确：

乔布斯那句话是怎么说的？「Stay hungry, stay foolish.」

推荐你阅读《Hackers & Painters: Big Ideas from the Computer Age》，非常的有趣。

错误：

乔布斯那句话是怎么说的？「Stay hungry，stay foolish。」

推荐你阅读《Hackers＆Painters：Big Ideas from the Computer Age》，非常的有趣。

名词

专有名词使用正确的大小写

大小写相关用法原属于英文书写范畴，不属于本文讨论内容，在这里只对部分易错用法进行简述。

正确：

欢迎来到 OpenCloudOS 文档库！

TencentOS Server 是腾讯云针对云的场景研发的 Linux 操作系统。

错误：

欢迎来到 opencloudos 文档库！

欢迎来到 OPENCLOUDOS 文档库！

欢迎来到 Opencloudos 文档库！

欢迎来到 opencloudOS 文档库！

tencentos server 是腾讯云针对云的场景研发的 linux 操作系统。

TENCENTOS SERVER 是腾讯云针对云的场景研发的 LINUX 操作系统。

TencentOS server 是腾讯云针对云的场景研发的 Linux 操作系统。

tencentOS Server 是腾讯云针对云的场景研发的 Linux 操作系统。

注意：当网页中需要配合整体视觉风格而出现全部大写／小写的情形，HTML 中请使用标淮的大小写规范进行书写；并通过 text-transform: uppercase;／text-transform: lowercase; 对表现形式进行定义。

不要使用不地道的缩写

正确：

我们需要一位熟悉 TypeScript、HTML5，至少理解一种框架（如 React、Next.js）的前端开发者。

错误：

我们需要一位熟悉 Ts、h5，至少理解一种框架（如 RJS、nextjs）的 FED。

争议

以下用法略带有个人色彩，即：无论是否遵循下述规则，从语法的角度来讲都是正确的。

链接之间增加空格

备注

此处我们建议将链接内容当作普通内容处理，即：如果前后内容均为中文且链接名称为中文，则不需要在链接前后增加空格。否则，在英语/数字与中文之间增加空格。

用法：

请提交一个 issue 反馈相关问题。

访问我们网站的最新动态，请点击这里进行订阅！

对比用法：

请提交一个 issue反馈相关问题。

访问我们网站的最新动态，请点击这里进行订阅！

简体中文使用直角引号

备注

此处我们建议使用普通引号（“” 与 ‘’）。

用法：

「老师，『有条不紊』的『紊』是什么意思？」