翻译正在进行中。

为了提供更加组织化、标准化且易于阅读的文档,MDN Web 文档写作规范明确了文本的组织方式、拼写规则、固定格式等相关内容。不过这些内容只是指导性的而不是严格规定的。因为比起格式我们对内容更感兴趣,所以没有必要前强迫自己在参与贡献之学习本规范。诚然,如果有一位勤劳的志愿者在之后编辑了你的文档使它更加符合本规范,也请不要感到惊讶或难过。

如果你正在寻找如何构建一个特定类型的页面的相关细节,请参阅MDN Web 文档页面布局规范

本规范主要适用于英文文档。 其他语言可能也有(也欢迎创建)相应的规范。 这些应该作为子页面发布在各个本地化小组的页面中。

对于那些为MDN以外的站点编写内容的规范,请参考 Mozilla 统一规范

基本规范

为了使文档更好的保持一致性,所有广泛发行的规范指南都是从指定一些非常基本的写作规范开始的。以下几个小节概述的这些基本规范将会对你很有帮助。

页面中的标题

页面中的标题不仅会用在搜索结果中,也会用在页面顶部的面包屑列表中来表示文档的层级结构。其中页面的标题(这里指显示在页面顶部以及搜索结果中的文章标题)可以与页面的“slug”不同,也就是网页URL中紧跟在"<locale>/docs/"之后那部分。

标题和标头的大写规则

页面的标题和章节的标头应当使用英文的语句式大写(只大写第一个单词和专有名词的首字母),而不是英文的标题式大写:

  • 正确: "A new method for creating JavaScript rollovers"
  • 错误: "A New Method for Creating JavaScript Rollovers"

我们还有很多旧的页面是在这条规范确立之前就已经发布了的。所以只要你乐意,你也可以根据需要来更新它们的标题。我们也正在逐步完善它们。

选择标题和slugs

页面的slugs应该保持简短;当创建一个新层级时,新层级的slug只应该由一到两个单词组成。

另一方面,页面的标题长度是没有限制的,只要它们合理,并且表意明确。

创建新的子目录

当你需要添加一些关于某个主题或某个领域的文章时,你通常需要创建一个引导页,然后为每篇独立的文章添加子页面。引导页开篇应当用一两段话来描述一下当前主题或技术,然后添加一个描述了对应子页面内容的列表。你可以使用那些我们已经创建好了的宏,把相关的子页面自动插入到列表中。

例如,看下JavaScript教程的子目录,它的结构应该像下面这样:

请尽量避免把你的文章放置在层次结构的顶层,这会使网站的速度降低,并让网站的搜索和导航效率低下。

部分,段落和换行符

以降序使用标题级别:<h2>然后<h3>,然后<h4>,而不跳过级别。 H2是允许的最高级别,因为H1是为页面标题保留的。如果您需要超过三到四层的标题,您应该考虑将文章分成几个带着陆页的小文章,并使用NextPreviousPreviousNext宏。

键盘上的Enter(或Return)键开始新的段落。要插入一个没有空格的换行符,按住Enter键的同时按住Shift键。

不要创建单个小节 - 您不会将主题细分为一个主题。它可以是两个小标题或更多,或者根本没有。

不要碰撞头,这是标题后立即标题。除了看起来很可怕之外,如果每一个标题都至少有一个简短的介绍,那么介绍下面的小节就会对读者有所帮助。

文档标签和贡献者

 此页面的贡献者: Dousy, DennisWang, suncn, WynnChen, zmh_w, OlingCat
 最后编辑者: Dousy,