MDN 样式指南

MDN 样式指南描述了文本的组织方式、拼写和格式等问题，以求能以一种有组织、标准化且易于阅读的方式呈现文档。这些内容只是指导原则而非强制规定。我们关注内容甚于格式，因此并不是非要先学好样式指南才能开始做贡献。不过，稍后可能会有勤劳的志愿者修改你的作品，以求符合本指南，碰到这种情况时无需惊讶，也别沮丧。

如果你正在寻找某种特定类型页面具体应当如何结构化，参见页面布局指南。

本指南中语言方面的内容主要针对英语文档。其它语言可以拥有（且欢迎创建）自己的样式指南。它们应作为本地化团队页面的子页面发布。

为 MDN 以外的站点所写的内容，其应用的样式标准可参考一体化 Mozilla 样式指南.

基本原则

要制定任何大规模的出版物样式指南，都最好从一些用于帮助文档保持一致性的最基本文本标准开始。后继章节将概述这些基本原则。

页面标题

在搜索结果中用到页面标题，在页面顶部展现页面层级结构的面包屑到行列中也用到页面标题。页面标题（显示于页面顶部和搜索结果中）可以与页面的“缩略名(slug)”不同。缩略名出现于URL中，即跟随在“<locale>/docs/”后面的那个部分。

标题的大小写

页面标题与章节标题应当使用一般句子的大小写方式（只有句首单词和专有名词的首字母大写），而非新闻标题式的大小写方式：

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

有不少页面是在本样式规则确立之前编写的。只要你愿意，随时可以对它们进行必要的更新。我们正在逐步处理。

选择标题与缩略名(slug)

页面的缩略名应保持简短；创建新的层级时，该层级在缩略名中应当只有一两个单词。

另一方面，页面标题，在合理范围内，长度随意，且应当是描述性的。

创建新子树

如果需要针对某个话题或主题领域添加若干文章，典型的做法是建立一个着陆页(landing page)，然后分别为每篇文章添加子页面。着陆页开头应当是一两段对该主题或技术的描述，接下来是带有各个页面描述的子页面列表。我们已经建好一些宏，通过它们可以自动将页面插入列表中。

以 JavaScript 指南为例，它的结构如下：

避免将文章放在层级结构的顶层，这样会拖慢站点的速度，并且使搜索和站点导航的效果变差。

章节、段落与换行

按递减顺序使用各个标题级别：首先 <h2>，其次 <h3>，再次 <h4>，不要跳过级别。允许使用的最高级别是 H2，因为 H1 要留给页面标题。如果标题要超过三或四个级别，应当考虑将文章拆分成一系列更小的文章和相应的着陆页，通过 Next、Previous 和 PreviousNext 这几个宏将它们链接在一起。

按回车键开启新段落。如果要另起一行又不想中间有空白，按住 Shift 键同时按回车。

不要建立单一的子章节——你并不会把一个主题细分为一部分。要么有两个或更多子标题，要么就根本一个都没。

避免在标题后面紧跟另一个标题。这样看起来很糟糕，并且对于读者来说，在每个标题后都至少有段介绍子章节的简介会很有帮助。

文本格式与样式

用“格式样式”下拉菜单可以把预定义的样式应用到选定内容上。

“注解”样式用于表达重要的注解内容，就像本条这样。

类似地，“警告”样式用于创建警告框，就像本条这样。

除非有明确的指示，否则不要使用 HTML 的style 属性来手工指定内容样式。如果无法靠预定义类型搞定，请到 #mdn 寻求帮助。

示例代码的样式与格式

制表符与断行

在所有代码样本中，都按每个制表符两个空格的标准用空格缩进。代码缩进要清晰，左花括号("{")应当与开启这个块的语句在同一行。例如：

if (condition) {
  /* handle the condition */
} else {
  /* handle the "else" case */
}

不允许长代码行水平延伸到需要水平滚动才能阅读的地步。取而代之的是，在自然中断点处断行。下面是一些例子：

if (class.CONDITION || class.OTHER_CONDITION || class.SOME_OTHER_CONDITION
       || class.YET_ANOTHER_CONDITION ) {
  /* something */
}

var toolkitProfileService = Components.classes["@mozilla.org/toolkit/profile-service;1"]
                           .createInstance(Components.interfaces.nsIToolkitProfileService);

内联代码格式

用“代码”按钮（标记是两个尖括号"<>"）来把内联代码样式应用到函数名、变量名、方法名上（这其实是用了<code> 元素）。例如，“frenchText() 函数”

方法名后面应当跟有一对括号：doSomethingUseful()。括号可以帮助将方法与其他代码术语区分开来。

语法高亮

整行（或多行）代码应当用语法高亮来格式化，而非 <code> 元素。点击工具栏上的 "pre" 按钮来创建预格式化的内容框，随后在其中写下代码。然后，保持文本输入光标停留在代码框中，点击"pre"按钮右边的语言列表按钮，选择恰当的语言，如右边的屏幕截图所示。以下例子展示了按 Javascript 进行格式化后的文本：

for (var i = 0, j = 9; i <= 9; i++, j--)
  document.writeln("a[" + i + "][" + j + "]= " + a[i][j]);

如果没有合适的转化可用，那么用 pre 标记同时不指定任何语言（语言列表中的“不高亮”）。

x = 42;

HTML 元素风格参考

关于 HTML 元素，有一些具体规则需要遵守。这些规则为元素及其组件生成一致的描述。同时，也确保链接到正确的详细文档。

元素名: 用 HTMLElement 宏，这将建立通向此元素相应页面的链接。例如，写下 {{HTMLElement("title")}} 将生成 "<title>"。If you don't want to create a link, enclose the name in angle brackets and use "Code (inline)" style (e.g., <title>).
属性名: 用粗体.
属性定义: 对定义的术语用 htmlattrdef 宏（例如，{{htmlattrdef("type")}}），这样它能够链接到其他网页，接着对参考属性定义用 htmlattrxref 宏（例如，{{htmlattrxref("attr","element")}}）。
属性值: 用“代码（内联）”样式，同时，除非示例代码中的语法确实需要，字符串两边不要有引号。例如：当元素的 type 属性设为 email 或 tel 时……
为属性打上标签: 使用诸如 HTML5 这样的标签时需要仔细考量。例如，将其用在加粗的属性名旁边，但并不是在正文中每次出现加粗的属性名时都用。

拉丁缩写

在注解和括号中

常见的拉丁缩写(etc., i.e., e.g.)可用于括号表达或注解中。在这些缩写中，要用句点（.）。
- 正确：Web browsers (e.g. Firefox) can be used ...
- 错误：Web browsers e.g. Firefox can be used ...
- 错误：Web browsers, e.g. Firefox, can be used ...
- 错误：Web browsers, (eg: Firefox) can be used ...

在连续文本中

在常规文本中（即，注解与括号之外的文本），使用与这些缩写等价的英语表达。
- 正确：... web browsers, and so on.
- 错误：... web browsers, etc.
- 正确： Web browsers such as Firefox can be used ...
- 错误：Web browsers e.g. Firefox can be used ...

拉丁文本的含义与等价的英语表达

缩写	拉丁文	英语
cf.	confer	compare 对比
e.g.	exempli gratia	for example 例如
et al.	et alii	and others 以及其他
etc.	et cetera	and so forth, and so on 等等 / 及其他
i.e.	id est	that is, in other words 换言之
N.B.	nota bene	note well 注意
P.S.	post scriptum	postscript 附言 / 再者

任何时候都要考虑一下用拉丁缩写是不是真的有收益。部分拉丁缩写很少使用，很多读者不明白其意思。其他的那些也常常会被互相混淆。假如选择使用拉丁缩写，请确保你自己没有用错。例如，一个常见的错误是把"e.g."与"i.e."混淆。

首字母缩略词与缩写

大写与句点

首字母缩略词与缩写都要全大写并删除其中的句点，包括诸如"US"和"UN"这样的组织名称。

正确：XUL
错误：X.U.L.; Xul

展开形式

页面上第一次提到某个术语时，用户可能并不熟悉首字母缩略词的展开形式。如果不确定，请将其展开，或者，更好的办法是，链接到描述此技术的文章或词汇表条目。

正确："XUL (XML User Interface Language) is Mozilla's XML-based language..."
错误："XUL is Mozilla's XML-based language..."

首字母缩略词与缩写的复数形式

对于首字母缩略词与缩写的复数情况，在后面加s。不要用撇号(')。绝对不要。请别用。

正确：CD-ROMs
错误：CD-ROM's

大小写

在正文中，使用标准的英语大小写规则，同时首字母大写"World Wide Web"和"Web"。

键盘键位应当用句子形式的大小写规则，而非全大写。例如，"Enter"而非"ENTER"。

缩略

我们的写作风格趋于休闲，因此只要你想，可以随意使用缩略（例如"don't", "can't", "shouldn't"）。

复数形式

使用英语风格的复数，而不是拉丁式的或希腊文影响的形式。

正确：syllabuses, octopuses
错误：syllabi, octopi

断字

如果复合词的前缀部分最后一个字母是一个元音，且与字根的第一个字母一样，则需要断字。

正确：email, re-elect, co-op
错误：e-mail, reelect, coop

中性语言

在写任何与性别无关的主题时，使用中性语言都是个好主意，能使文字尽可能具有包容性。因此，举个例子说，如果谈论的是具体某位男性的行为，用 he/his 是可以的，但如果主题是任何性别的人，he/his 就不太恰当了。

看下面这个例子：

弹出对话框来询问用户是否允许网页使用他的(his)摄像头。

弹出对话框来询问用户是否允许网页使用她的(her)摄像头。

这两个版本都是限定性别的。要解决这个问题，使用中性代词：

弹出对话框来询问用户是否允许网页使用其(their)摄像头。

MDN 允许使用这种常见语法（使用上是有争议的）来解决英语缺乏中性用法的问题。将第三人复数用作中性代词（即，用 "they," them", "their" 和 "theirs"）是种可接受的实践方法，通常称之为"singular 'they.'"

也可以同时使用两种性别：

弹出对话框来询问用户是否允许网页使用他的/她的(his/her)摄像头。

或者将用户也使用复数：

弹出对话框来询问用户们(users)是否允许网页使用他们的(their)摄像头。

最佳解决方案，显然，是重写一下，消除代词：

弹出对话框来请求用户给予使用摄像头的权限。

弹出请求用户给予使用摄像头的权限的对话框。

处理这个问题，最后这种方式无疑更好一些，不仅在语法上更加正确，同时还省却了一些由不同语言间处理性别问题的差异所带来的复杂性。这种解决方式使得无论是对读者还是对本地化人员而言，翻译都更加轻松。

数与数词

日期

对于日期（不包括示例代码中的日期）使用"January 1, 1990"的格式。

正确：February 24, 2006
错误：February 24th, 2006; 24 February, 2006; 24/02/2006

也可以用 YYYY/MM/DD 的格式。

正确：2006/02/24
错误：02/24/2006; 24/02/2006; 02/24/06

年代

对于年代，用"1990s"的格式。不要用撇号(')。

正确：1990s
错误：1990's

数词的复数形式

对于数词的复数情况，在后面加"s"。不要用撇号(')。

正确：486s
错误：486's

逗号

在连续文本中，只有5位或者或者更多位的数字才加逗号分段。

正确：4000; 54,000
错误：4,000; 54000

标点符号

系列逗号

使用系列逗号。系列逗号（又称“牛津逗号”）是指在三个或更多个项目并列结构中，出现在连词前的逗号。

正确：I will travel on trains, planes, and automobiles.
错误：I will travel on trains, planes and automobiles.

与之相反，一体化 Mozilla 样式指南明确指出不要使用系列逗号。MDN 是此规则的一个例外。

拼写

存在多种拼写法的单词，以Dictionary.com上第一个条目的写法为准。不要使用变体拼写。

正确：localize, honor
错误：localise, honour

术语

过时(obsolete) vs. 废弃(deprecated)

弄清术语 过时(obsolete) 与 废弃(deprecated) 之间的区别是非常重要的。

过时(obsolete)：: 在 MDN，术语过时表示某 API 或技术不仅不再推荐，同时浏览器中也不再对其进行实现。对于 Mozilla 专有技术，API 在 Mozilla 代码中不再有所实现；对于 Web 标准技术，API 或特性在当前常见通用浏览器中不再受支持。
废弃(deprecated)：: 在 MDN，术语废弃表示某 API 或技术不再推荐，但仍然有所实现并可能仍可运作。理论上说，这些技术最终都会变为过时并移除，因此应当停止使用它们。对于 Mozilla 专有技术，API 在 Mozilla 代码中仍然有所支持；对于 Web 标准技术，API 或特性在最近一个版本的标准定义中有所删改。

HTML 元素

用“元素”来指代 HTML 与 XML 元素，而非“标签”。另外，基本上在所有情况下都应当在元素名外面加上"<>"，并且应当应用 <code> 样式。同样，至少每个章节中对特定元素的第一次引用应当使用 HTMLElement 宏，来建立通向此元素文档的链接（除非刚好是在编写此元素的参考文档页）。

正确：<span> 元素
错误：span 标签

用户界面操作

在任务序列中，用祈使语气描述用户界面操作。. 用户界面元素通过其标签(label)与类型来识别。

正确：点击编辑按钮。
错误：点击编辑。

语态

首选主动语态，但用被动语态也可以，因为我们的内容有非正式的感觉。但是要尽力保持一致。

wiki 标记与用法

链接

wiki 能成为强大的学习与教学工具，链接是很大一部分原因。下面是一些基本信息，在我们的编辑指南中的在 MDN 创建与编辑链接处有完整的指南。

外部链接

用这个宏自动建立通向某个 Bugzilla bug 的链接：

{{Bug(322603)}}

其结果是：

bug 322603

对于 WebKit bug，用这个宏：

{{Webkitbug("322603")}}

其结果是：

WebKit bug 322603

URL scheme（URL 方案）

由于安全方面的原因，应当只创建使用以下 scheme 的链接：

https://
https://
ftp://
mailto:

其他 scheme 可能运作也可能不运作，但全都不受支持且有可能被编辑人员移除。

尤其是，绝对不要用 about: 或 chrome:// scheme，它们无法正常工作。同样，大部分现代浏览器也会阻止 javascript: 及 jar: scheme。

页面标签(tag)

标签可以提供页面的有关元数据、表明页面的内容有具体需要改进之处。在 wiki 上的每个页面都应当有标签。关于打标签的细节信息，参见如何正确为页面打标签指南。

在编辑模式中，标签界面出现在页面底部，大致上看起来是这样：

在 MDN 上添加删除标签的用户交互的屏幕截图

要添加标签，点击位于标签列表末尾的编辑框并输入想要添加的标签名称。随着输入，标签会自动补全。按回车即可提交新标签。如有需要，每篇文章可以拥有任意数量标签。例如，一篇关于在 AJAX 编程中JavaScript 的使用的文章可以同时用"JavaScript"和"AJAX"作为标签。

要移除标签，只要点击标签上小小的"X"图标即可。

标记需要进一步工作的页面

除了用标签来跟踪有关文档质量和内容的信息，我们也用标签来将文章标记为需要特定类型的工作。

标记过时页面

对于并非当前状态的页面，用以下标签：

Junk（垃圾）：对垃圾页面使用此标签。页面是错误创建的，或内容实在太差而应当删除。具有此标签的页面会时不时被删除。
Obsolete（过时）：对技术上已被取代、但仍在特定上下文中有用的内容使用此标签。例如，在 HTML5 中已过时但在 HTML4.01 中仍有效的 HTML 元素。还可以用 obsolete_header 宏来为主题放上一个突出的banner提示。
Archive（归档）：对技术上已被取代且不再有用的内容使用此标签。如果有可能，为此主题添加一个注解，将读者导向更新的主题。例如，描述如何使用 Mozilla CVS 仓库的页面应当将读者导向当前关于使用 Mercurial repos 的主题。（如果没有相应的当前主题存在，用上 NeedsUpdate 标签，并且在Talk页面上添加一个说明。）具有 Archive 标签的页面最终将从 MDN 主内容区移动到归档区。

SEO 摘要

SEO 摘要提供页面的简短描述。对于抓取网站的机器人来说，这将做为文章的摘要，随后显示在这个页面相应的搜索结果中。同时，在 MDN 内部自动建立着陆页的宏也会用到它。

默认情况下，页面的第一个段落将作为 SEO 摘要。然而，可以通过对段落应用所见即所得编辑器中的“SEO 摘要”样式来覆盖此行为。

着陆页

着陆页是指站点中位于主题区域根源位置的页面，诸如 CSS 或 HTML 的主页面。它们的标准格式由三个区域组成：

简短（通常是一个段落）的概述，说明技术是什么以及如何使用它。更多提示参见Writing a landing page overview。
带有恰当标题的两栏链接列表。相关原则参见 Creating a page link list。
可选的“浏览器兼容性”区段，出现在页面底部。

建立页面链接列表

MDN 着陆页的链接列表区段由两栏组成。这是用以下 HTML 创建的：


  
    ... 左栏内容 ...
  
  
    ... 右栏内容 ...

左栏是文章列表，顶部有一个 <h2> 标题，此标题说明了这是一个关于某主题的文章列表（例如“关于 foo 的文档与教程”）；这个标题应当用"Documentation" CSS 类。接下来是一个文章的 <dl> 列表，每篇文章的链接在 <dt> 块中，文章的一两句简短摘要则出现在相应的 <dd> 块。

右栏应当包含以下区段中的一个或多个，按顺序分别是：

从社区获得帮助: 这里要提供关于此主题可用的 IRC 频道和邮件列表信息。标题应当用"Community"类
工具: 能够帮助用户使用在 MDN 此区域中所描述技术的工具列表。标题应当用"Tools"类。
相关主题: 通往其他相关技术的着陆页的链接列表。标题应当用"Related_Topics"类。

<<<一旦我们完成着陆页标准之后就会来写完这些>>>

使用、插入图像

在一些时候，在文章中提供图像会很有帮助，尤其当文章非常技术性时。若要包含图像：

将想要的图像文件附加到文章（编辑模式下在文章底部）
在所见即所得编辑器中建立图像
所见即所得编辑器中，在附件下拉列表中选择最近创建的附件，即是需要的图像
按下确认。

其他参考

首选样式指南

如果对这里未包含的用法与样式有疑问，推荐参考Economist style guide，或者，如果还是没找到，Chicago Manual of Style。

首选字典

拼写问题请参考Dictionary.com。此网站的拼写检查使用的是美式英语。请勿使用变体拼写法（例如，要用 color 而非 colour）。

随着时间推移，我们会逐渐扩展此指南。所以如果你有任何此文档未包含的具体问题，请发给 MDC 邮件列表或项目负责人，好让我们知道应当添加哪些内容。

MDN 专用

MDN 常用宏，带有解说。

语言、语法、拼写

如果对改进写作与编辑能力有兴趣，以下资源对你可能有用。

On Writing Well, by William Zinsser (Amazon link)
Style: The Basics of Clarity and Grace, by Joseph Williams and Gregory Colomb (Amazon link)
Common Errors in English
English Grammar FAQ (alt.usage.english)
Bob's quick guide to the apostrophe, you idiots (funny)
Merriam-Webster's Concise Dictionary of English Usage (Amazon link): Scholarly but user-friendly, evidence-based advice; very good for non-native speakers, especially for preposition usage.
English Language and Usage StackExchange: Question and answer site for English language usage.