编写风格指南

通用编写指南

目标是编写包含读者理解当前主题所需所有信息的页面。

以下小节提供了实现此目标的建议

• 考虑您的目标受众
• 考虑编写的三 C 原则
• 包含相关示例
• 提供描述性介绍
• 使用包容性语言
• 以 SEO 为导向进行编写

考虑您的目标受众

请记住您正在撰写的内容的目标受众。例如，一篇关于高级网络技术的页面可能不需要像典型的网络页面那样详细介绍基本网络概念。请记住这些是指导方针。其中一些提示可能不适用于所有情况。

考虑编写的三 C 原则

良好写作的三个 C 是清晰（Clear）、简洁（Concise）和一致（Consistent）。

• 清晰：确保您的文字清晰简洁。通常，使用主动语态和明确的代词。写短句子，每句只表达一个想法。在使用新术语之前，先定义它们，同时考虑目标受众。
• 简洁：编写任何文档时，了解要说什么很重要。如果您提供过多细节，页面会变得冗长难读，并且很少会被使用。
• 一致：确保在整个页面以及多个页面上使用相同的措辞。

包含相关示例

通常，添加示例或真实场景可以更好地解释您正在撰写的内容。这有助于读者以更具体、更实用的方式理解概念性和程序性信息。

您应该使用示例来澄清每个参数的用途，并澄清可能存在的任何极端情况。您还可以使用示例来演示常见任务的解决方案和可能出现问题的解决方案。

提供描述性介绍

确保第一个标题前的开头段落充分总结了页面将涵盖的信息，以及读者在阅读内容后可能能够实现的目标。这样，读者可以快速确定该页面是否与其关注点和预期学习成果相关。

在指南或教程中，引言段落应告知读者将涵盖的主题以及读者应具备的先决知识（如果有）。开头段落应提及正在记录或讨论的技术和/或 API，并附有相关信息的链接，并应提供文章内容可能在哪些情况下有用的提示。

• 简短引言示例：这个引言示例太短了。它遗漏了太多信息，例如“描边”文本到底是什么意思，文本在哪里绘制，等等。

  CanvasRenderingContext2D.strokeText() 绘制一个字符串。

• 冗长引言示例：此示例的引言已更新，但现在太长了。包含了过多的细节，并且文本过于深入地描述了其他方法和属性。相反，引言应该侧重于 strokeText() 方法，并应参考描述其他细节的适当指南。

  调用时，Canvas 2D API 方法 CanvasRenderingContext2D.strokeText() 使用当前的画笔颜色，描边指定字符串中的字符，从指定坐标开始。在计算机图形学术语中，“描边”文本意味着绘制字符串中字形的轮廓，而不填充每个字符的颜色。

  文本使用上下文中 font 属性中指定的当前字体绘制。

  文本相对于指定坐标的放置由上下文的 textAlign、textBaseline 和 direction 属性决定。textAlign 控制字符串相对于指定 X 坐标的放置；如果值为 "center"，则字符串从 x - (stringWidth / 2) 开始绘制，将指定的 X 坐标放在字符串的中间。如果值为 "left"，则字符串从 x 的指定值开始绘制。如果 textAlign 为 "right"，则文本绘制成在指定的 X 坐标处结束。

  (…)

  您可以选择提供第四个参数，让您指定字符串的最大宽度（以像素为单位）。如果提供此参数，文本在绘制时会被水平压缩或缩放（或以其他方式调整）以适应该宽度空间。

  您可以调用 fillText() 方法来绘制填充颜色的字符串字符，而不是只绘制字符轮廓。

• 适当引言示例：以下部分为 strokeText() 方法提供了更好的概述。

  CanvasRenderingContext2D 方法 strokeText()，作为 Canvas 2D API 的一部分，描边（绘制轮廓）指定字符串中的字符，锚定在给定 X 和 Y 坐标指示的位置。文本使用上下文的当前 font 绘制，并根据 textAlign、textBaseline 和 direction 属性进行对齐和定位。

  有关更多详细信息和示例，请参阅绘图图形页面上的 文本 部分以及我们的主要主题文章 绘制文本。

使用包容性语言

MDN 拥有广泛而多元的受众。我们强烈建议尽可能保持文本的包容性。以下是文档中常用术语的一些替代方案

• 避免使用 master 和 slave 术语，而是使用 main 和 replica。
• 将 whitelist 和 blacklist 替换为 allowlist 和 denylist。
• Sanity 应该替换为 coherence。
• 不要使用 dummy，而是使用 placeholder。
• 您不应该在文档中使用 crazy 和 insane 术语；但是，如果出现这种情况，请考虑使用 fantastic 代替。

在任何与性别无关的写作中，最好使用中性语言。例如，如果您正在谈论某个男性的行为，使用“他”/“他的”是没问题的；但如果主题是任何性别的个人，那么“他”/“他的”就不合适了。

让我们看以下示例

• 不正确：“一个确认对话框询问用户是否希望允许网页使用他的摄像头。”
• 不正确：“一个确认对话框询问用户是否希望允许网页使用她的摄像头。”

两种版本都具有性别特异性。为了解决这个问题，请使用中性代词，例如

• 正确：“一个确认对话框询问用户是否希望允许网页使用他们的摄像头。”

另一个选择是将用户变为复数，例如

• 正确：“一个确认对话框询问用户是否希望允许网页使用他们的摄像头。”

当然，最好的解决方案是重写并消除代词

• 正确：“出现一个请求用户允许访问摄像头的确认对话框。”
• 正确：“出现一个询问用户是否允许使用摄像头的确认对话框。”

处理此问题的最后一个例子可以说更好。它不仅在语法上更正确，而且消除了处理不同语言中性别规则可能大相径庭的一些复杂性。这种解决方案可以使读者和翻译人员的翻译更容易。

使用易于理解的语言

避免使用空间和方向词，例如“上方”、“下方”、“左侧”、“右侧”或“此处”。这些术语假定了一个特定的视觉布局，这可能不适用于所有用户。它们也可能不清楚或具有误导性——特别是对于依赖屏幕阅读器或阅读翻译内容的用户，其中方向性语言可能模糊不清或难以准确翻译。在响应式布局中，内容的位置可能会根据屏幕大小而变化，这种方向性引用可能会变得不准确。这种语言可能会阻碍可访问性，并使所有用户更难导航或理解内容。

相反，使用描述性短语，清楚地标识所引用的部分、概念或元素。通过其标题或副标题引用部分，并通过其演示或包含的内容引用示例或代码片段。

例如

• 正确：“请参阅本页面稍后的可访问性部分。”

• 不正确：“请参阅下面的可访问性部分。”

• 正确：“在以下代码示例中，我们使用 CSS 过渡来动画一个圆形。”

• 不正确：“在下面的代码示例中，我们使用 CSS 过渡来动画一个圆形。”

• 正确：“这个概念在前面题为‘创建媒体查询’的部分中进行了解释。”

• 不正确：“这个概念在上面一节中进行了解释。”

此外，避免使用模糊的链接文本，如“点击此处”或“阅读本文”。描述性链接文本为所有读者提供了更好的上下文，并改善了辅助技术用户的体验。

• 正确：“了解有关如何排序弹性项目的更多信息。”
• 不正确：“点击此处了解更多信息。”
• 不正确：“阅读本文了解更多信息。”

通过遵循这些指南，您可以帮助 MDN 文档易于访问、清晰并可供所有人使用，无论他们如何访问页面。

以 SEO 为导向进行编写

尽管 MDN Web 文档中任何写作的主要目标始终是解释和介绍开放网络技术，以便开发人员能够快速学习他们想要做的事情或找到他们需要知道的小细节以完善他们的代码，但重要的是他们能够找到我们编写的材料。我们可以通过在写作时牢记搜索引擎优化（SEO）来实现这一目标。

本节涵盖了内容的标准做法、建议和要求，以帮助确保搜索引擎能够轻松地对我们的材料进行分类和索引，从而确保读者能够轻松找到他们所需的信息。SEO 指南包括确保作者和编辑所处理的每个页面都经过合理的设计、编写和标记，以便为搜索引擎提供正确索引文章所需的上下文和线索。

在编写和审阅内容时，请牢记以下核对清单，以帮助确保页面及其相邻页面能够被搜索引擎正确索引

• 确保页面之间不过于相似：如果不同页面的内容在文本上相似，即使它们不是同一事物，搜索引擎也会假定这些页面是关于同一事物的。例如，如果一个接口具有 width 和 height 属性，那么在文档化这两个属性的两个页面上，文本很容易惊人地相似，只是替换了几个词并使用了相同的示例。这使得搜索引擎很难区分哪个是哪个，它们最终会共享页面排名，导致两者都比应有的更难找到。

  因此，重要的是确保每个页面都有自己的内容。以下建议可以帮助您实现这一目标

  • 解释更多独特的概念：考虑用例，其中可能存在比人们想象的更多的差异。例如，在文档化 width 和 height 属性的情况下，也许可以写一些关于水平空间和垂直空间如何不同使用的方式，并提供关于适当概念的讨论。也许您可以提及 width 在为侧边栏腾出空间方面的使用，而 height 用于处理垂直滚动或页脚。包含有关可访问性问题的信息也是一个有用且重要的想法。
  • 使用不同的示例：在这些情况下，示例通常比正文文本更相似，因为示例可能一开始就使用了相似的方法或属性（或所有），因此在重用时无需进行任何实际更改。因此，请删除示例并编写一个新的，或者至少提供多个示例，其中至少有一些是不同的。
  • 为示例添加描述：应包含对示例功能的概述，以及根据主题的复杂性和目标受众，以适当的详细程度说明其工作原理。

  避免过度相似的最简单方法当然是，如果时间允许，从头开始编写每篇文章。

• 确保页面不要太短：如果页面上的内容过少（在 SEO 术语中称为“瘦页面”），搜索引擎将无法准确（或根本无法）对这些页面进行分类。内容过短的页面很难被找到。作为指导原则，请确保 MDN Web 文档上的页面长度不少于约 300 字。不要人为地增加页面长度，但尽可能将此指南视为最低目标长度。

  这些基本指南可以帮助您创建内容充足的页面，以便正确搜索，而无需用不必要的文本来堆砌它们

  • 避免占位内容（stubs）：显然，如果文章是占位内容或缺少内容，请添加它。我们试图避免 MDN Web Docs 上出现完全的“占位”页面，尽管它们确实存在，但有很多页面缺少大部分内容。
  • 审阅页面结构：审阅页面，确保其结构与其页面类型正确对应。检查以确保所有部分都存在并具有适当的内容。
  • 确保完整性：审阅各部分，确保没有遗漏任何信息。确保所有参数都已列出并解释。确保所有异常情况都已涵盖——这是内容特别容易缺失的地方。
  • 确保所有概念都充分阐述：快速解释某事很容易，但要确保涵盖所有细微之处。是否有特殊情况？是否有读者可能需要了解的已知限制？
  • 添加示例：应提供涵盖所有参数的示例，或者至少是初学者到中级用户可能使用的参数（或属性、或特性）的示例，以及任何需要额外解释的高级示例。每个示例前面都应有一个概述，说明示例将做什么，理解它可能需要哪些额外知识等等。示例之后（或穿插在示例片段之间）应有文本解释代码如何工作。不要吝啬示例中的细节或错误处理。请记住，用户会复制并粘贴您的示例以在他们自己的项目中使用，并且您的代码会最终用于生产站点！请参阅我们的代码示例指南以获取更多有用信息。
  • 解释用例：如果所描述的功能有特别常见的用例，请讨论它们！不要假设用户会发现所记录的方法可以用于解决常见的开发问题，而应实际添加一个关于该用例的部分，并附上示例和解释示例如何工作的文本。
  • 添加图像信息：所有图像和图表都应包含正确的 alt 文本。此文本以及表格和其他图表的标题都很重要，因为蜘蛛无法爬取图像，因此 alt 文本会告诉搜索引擎爬虫嵌入式媒体包含什么内容。

    注意： 不建议为了操纵搜索引擎排名而包含过多关键词或与功能无关的关键词；这种行为很容易被发现并受到惩罚。同样，不要在实际页面内添加重复的、无用的材料或关键词堆，以试图增加页面大小和搜索排名。这弊大于利，既损害了内容的可读性，也损害了我们的搜索结果。

• 关注主题内容：围绕页面的主题而不是特定关键词撰写内容要好得多。一个给定主题很可能包含许多关键词；事实上，许多 SEO 专家会编制一个包含 5-100 个不同关键词（根据长度不同，包括短尾、中尾和长尾关键词）的列表，以便在文章中包含。这样做将使您的措辞多样化，减少重复。

编写风格

除了用英语书写语法正确的句子外，我们建议您遵循以下准则，以保持 MDN Web Docs 内容的一致性。

• 缩写和首字母缩略词
• 大写
• 缩写形式
• 数字和数字符号
• 复数形式
• 撇号和引号
• 逗号
• 连字符
• 拼写
• 术语
• 语态

缩写和首字母缩略词

缩写是较长单词的缩短版本，而首字母缩略词是使用短语中每个单词的首字母创建的新词。本节描述了缩写和首字母缩略词的指南。

• 展开：在页面中首次提及某个术语时，请展开用户可能不熟悉的首字母缩略词。如有疑问，请展开该术语。更好的是，将其链接到描述该技术的文章或词汇表条目。

  • 正确：“XUL（XML 用户界面语言）是 Mozilla 基于 XML 的语言...”
  • 不正确：“XUL 是 Mozilla 基于 XML 的语言...”

• 大写和句号：所有缩写和首字母缩略词，包括“US”和“UN”等组织，都使用全大写并删除句号。

  • 正确：XUL
  • 不正确：X.U.L.; Xul

• 拉丁语缩写：您可以在括号表达式和注释中使用常见的拉丁语缩写（etc.，i.e.，e.g.）。在这些缩写中使用句号，后跟逗号或其他适当的标点符号。

  • 正确：Web 浏览器（例如 Firefox）可以使用...
  • 不正确：Web 浏览器 e.g. Firefox 可以使用...
  • 不正确：Web 浏览器, e.g. Firefox, 可以使用...
  • 不正确：Web 浏览器, (eg: Firefox) 可以使用...

  在常规文本中（即，注释或括号之外的文本），使用缩写的英文等效词。

  • 正确：……网页浏览器等等。

  • 不正确：……网页浏览器，etc.

  • 正确：像 Firefox 这样的网页浏览器可以使用...

  • 不正确：网页浏览器 e.g., Firefox 可以使用...

  下表总结了拉丁语缩写的含义和英语等效词

  缩写	拉丁语	英语
  cf.	confer	比较
  e.g.	exempli gratia	例如
  et al.	et alii	及其他人
  etc.	et cetera	等等，诸如此类
  i.e.	id est	也就是说，换句话说
  N.B.	nota bene	请注意
  P.S.	post scriptum	附言

  注意： 务必考虑使用拉丁文缩写是否真正有益。其中一些使用频率如此之低，以至于许多读者要么混淆其含义，要么根本不理解。

  另外，如果您选择使用它们，请务必正确使用。例如，请注意不要混淆“e.g.”和“i.e.”，这是一个常见的错误。

• 缩写和首字母缩略词的复数：对于缩写和首字母缩略词的复数，加 s。不要使用撇号。永远不要。拜托。

  • 正确：CD-ROMs
  • 不正确：CD-ROM's

• “Versus”、“vs.”和“v.”：如果使用缩写，“vs.”优于“v.”，并且可以在标题中使用。在文本的其他地方，请使用完整拼写形式“versus”。

  • 正确：this vs. that
  • 不正确：this v. that
  • 正确：this versus that

大写

在正文中使用标准英语大写规则，并将“World Wide Web”大写。单独使用“web”（或作为修饰语）和“internet”时，可以使用小写。

键盘键应使用句子式大写，而不是全大写。例如，“Enter”而不是“ENTER”。唯一的例外是您可以使用“ESC”来缩写“Escape”键。

某些词语应始终大写，例如包含大写字母的商标或源自人名的词语（除非该词语在代码中使用且代码语法要求小写）。一些示例如下

• 布尔（以英国数学家和逻辑学家 乔治·布尔 命名）
• JavaScript（Oracle Corporation 的商标，应始终按商标形式书写）
• Python、TypeScript、Django 以及其他编程语言和框架名称

一些工具名称和项目有其自己的品牌大写规则。这些可能需要全小写（“npm”或“webpack”）、全大写（“UNIX”、“GNOME”、“VIM”）或混合大小写（“TypeScript”、“macOS”或“jQuery”）的名称。

应始终使用官方网站或文档中的品牌大写，即使在句首也是如此。如果您对以小写字母开头的句子感到不适，我们建议您改写以避免此问题。例如，您可以说“您可以使用 npm 包管理器来...”而不是“npm 允许您...”。

缩写形式

我们的写作风格倾向于休闲，因此如果您愿意，可以随意使用缩写（例如，“don't”、“can't”、“shouldn't”）。

数字和数字符号

• 逗号：在常规文本中，仅在五位数及更大的数字中使用逗号。

  • 正确: 4000; 54,000
  • 不正确: 4,000; 54000

• 日期：对于日期（不包括代码示例中的日期），使用“January 1, 1900”格式。

  • 正确：February 24, 1906
  • 不正确：February 24th, 1906; 24 February, 1906; 24/02/1906

  或者，您可以使用 YYYY/MM/DD 格式。

  • 正确: 1906/02/24
  • 不正确: 02/24/1906; 24/02/1906; 02/24/06

• 年代：使用“1990s”格式。不要使用撇号。

  • 正确：1920s
  • 不正确：1920's

• 数字的复数：添加“s”。不要使用撇号。

  • 正确：486s
  • 不正确：486's

复数形式

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

• 正确：syllabuses, octopuses
• 不正确：syllabi, octopi

撇号和引号

不要使用“弯引号”。在 MDN Web Docs 上，我们只使用直引号和撇号。这是因为我们需要在两者之间选择一个以保持一致性。如果弯引号或撇号进入代码片段，即使是内联的，读者也可能会复制和粘贴它们，期望它们能够正常工作（但它们不会）。

• 正确：请不要使用 "curly quotes."
• 不正确：请不要使用 “curly quotes.”

逗号

以下列表描述了一些我们需要注意逗号使用规则的常见情况

• 引导性从句后：引导性从句是通常位于句子开头的从属从句。在引导性从句后使用逗号将其与随后的主句分开。

  • 示例 1
    • 正确：“In this example, you will learn how to use a comma.”
    • 不正确：“In this example you will learn how to use a comma.”
  • 示例 2
    • 正确：“如果您正在寻找指南，请参阅我们的写作风格指南。”
    • 不正确：“如果您正在寻找指南请参阅我们的写作风格指南。”
  • 示例 3
    • 正确：“在移动平台上，您通常会得到一个数字键盘来输入数据。”
    • 不正确：“在移动平台上您通常会得到一个数字键盘来输入数据。”

• 连词前：序列逗号（也称为“牛津逗号”）是出现在三个或更多项目系列中连词之前的逗号。在 MDN Web Docs 上，我们使用序列逗号。逗号也分隔列表中的每个项目。

  • 正确：“我将乘坐火车、飞机和汽车。”
  • 不正确：“我将乘坐火车、飞机和汽车。”

  在包含两个项目的列表中，不要在“and”和“or”之前使用逗号。

  • 正确：“我的狗既可爱又聪明。”
  • 不正确：“我的狗既可爱，又聪明。”

  如果“and”、“but”和“or”连接两个独立的从句，则在它们之前使用逗号。但是，如果句子因连词而变得非常长或复杂，请考虑将其改写为两个句子。

  • 示例 1
    • 正确：“您可以执行此步骤，但您需要注意文件设置。”
    • 不正确：“您可以执行此步骤但您需要注意文件设置。”
  • 示例 2
    • 正确：“我父亲虽然严厉但充满爱意。”
    • 不正确：“我父亲虽然严厉，但充满爱意。”

• 在“that”和“which”之前：限制性从句对于句子的含义至关重要，不需要逗号将其与句子的其余部分分开。限制性从句通常由“that”引入，不应在其前面加逗号。

  • 正确：“我们整理了一门课程，其中包含您实现目标所需的所有基本信息。”
  • 不正确：“我们整理了一门课程，其中包含您实现目标所需的所有基本信息。”

  非限制性从句提供附加信息，对句子的含义并非必不可少。非限制性从句通常由“which”引导，其前面应加逗号。

  • 正确：“您编写了一个策略，它是每个功能允许的来源列表。”
  • 不正确：“您编写了一个策略它是每个功能允许的来源列表。”

• 在“such as”之前：如果“such as”是非限制性从句的一部分，并且其余部分是独立从句，则在“such as”之前使用逗号。

  • 正确：“Array 对象有多种操作数组的方法，例如连接、反转和排序。”
  • 不正确：“Array 对象有多种操作数组的方法 such as joining, reversing, and sorting them.”

  以下示例展示了何时不使用逗号和“such as”。在这种情况下，包含“such as”的从句对于句子的含义至关重要。

  • 正确：“通过添加音频和视频处理等功能，并通过 WebSockets 访问原始数据，Web 应用程序变得越来越强大。”
  • 不正确：“通过添加音频和视频处理等功能，并通过 WebSockets 访问原始数据，Web 应用程序变得越来越强大。”

连字符

复合词只有在前缀的最后一个字母是元音且与词根的第一个字母相同时才应使用连字符。

• 正确：re-elect, co-op, email
• 不正确：reelect, coop, e-mail

拼写

使用美式英语拼写。

一般来说，使用 Dictionary.com 的第一个条目，除非该条目被列为变体拼写或主要用于非美式英语形式。例如，如果您查找“behaviour”（在美式标准形式中添加了额外的 u），您会发现短语“主要用于英式英语”，后面是美式标准形式 “behavior” 的链接。不要使用变体拼写。

• 正确：localize, behavior, color
• 不正确：localise, behaviour, colour

我们安装了 cSpell 来捕捉拼写错误。它每周运行一次，并生成一份存储库中的拼写错误报告。您也可以使用以下命令在本地运行它

yarn lint:typos

在存储库中，我们维护着几个单词列表，位于.vscode/dictionaries，其中包含默认词典中没有的认可词。如果拼写检查器报告的单词有效，您可以将更多单词添加到这些列表中。请阅读.vscode/cspell.json以了解每个词典包含的内容以及我们拼写检查配置的详细信息。

术语

以下是我们使用某些技术术语的建议

• HTML 元素：使用“元素”一词指代 HTML 和 XML 元素，而不是“标签”。此外，元素应使用尖括号“<>”包裹，并使用反引号 (`) 进行样式设置。例如，在反引号内使用 <input> 将其样式化为 <input>，这是预期的。

  • 正确：<span> 元素
  • 不正确：span 标签

  在 MDN 上，您可以在 HTMLElement 宏中选择性地指定 HTML 元素，该宏将对元素进行样式设置，添加尖括号“<>”，并添加指向其参考页面的链接。

  • 使用反引号：<span>
  • 使用宏：<span>（Markdown 源代码：{{HTMLElement("span")}}）

• 参数与实参：MDN Web Docs 中首选的术语是 parameters。请尽可能避免使用“arguments”一词以保持一致性。

• 用户界面操作：在任务序列中，使用祈使语气描述用户界面操作。通过其标签和类型标识用户界面元素。

  • 正确：“点击编辑按钮。”
  • 不正确：“点击编辑。”

语态

虽然主动语态是首选，但被动语态也是可以接受的，因为我们的内容具有非正式的风格。但请尽量保持一致。

页面组件

本节列出了每个页面的不同部分（例如标题、注释、链接和示例）应遵循的指南。

• 代码示例
• 交叉引用（链接）
• 外部链接
• 缩短的 URL（短链接）
• 标题级别
• 图像及其他媒体
• 列表
• 另请参阅部分
• 子页面
• 短链接（slug）
• 标题

代码示例

MDN Web 文档中的一个页面可以包含多个代码示例。以下列表提供了为 MDN Web 文档编写代码示例时的一些推荐做法

• 每段示例代码应包括
  • 标题：一个简短的 ### (<h3>) 标题，描述通过代码示例演示的场景。例如，“使用偏移打印”和“恢复到上一层的样式”。
  • 描述：在示例代码之前提供一个简短的描述，说明您希望读者注意的示例具体内容。例如，“在以下示例中，CSS 中定义了两个级联层：base 和 special。”
  • 结果解释：在示例代码之后提供解释，描述结果以及代码如何工作。
• 通常，代码示例不仅应演示该功能的语法和用法，还应强调 Web 开发人员可能希望或需要使用该目的和情况。
• 如果您正在处理一段大型示例代码，将其分解为更小的逻辑部分以便单独描述可能更合理。
• 添加实时示例时，了解所有示例中相同类型（HTML、CSS 和 JavaScript）的代码块在运行示例之前会连接起来是很有帮助的。这使您可以将代码分解为多个片段，每个片段可以选择有自己的描述、标题等。这使得文档化代码变得极其强大和灵活。

要了解如何为 MDN Web Docs 样式化或格式化代码示例，请参阅我们的代码示例样式指南。

交叉引用（链接）

在 MDN 上通过标题引用另一个页面或页面的一部分时，链接文本应遵循句子式大小写（与页面或部分标题匹配）。即使链接文本与链接页面的标题或部分标题不同（可能是页面或部分标题中使用的字母大小写不正确），链接文本也应使用句子式大小写。链接文本周围不要使用引号。要通过标题引用 MDN 上的页面，请使用以下样式

• 正确：“请参阅弹性项目排序指南。”
• 不正确：“请参阅“弹性项目排序”指南。”

链接到页面内的部分时，请遵循一致的风格

• 正确：“有关更多信息，请参阅《内存管理》指南中的JavaScript 中的分配部分。”

如果您要链接到的部分在同一页面上，您可以使用描述性短语提示该部分的位置。

• 正确：“本概念将在本文档的可访问性部分详细描述。”
• 不正确：“本概念将在下面的可访问性部分详细描述。”

在 MDN 上，另一种链接到参考页面的方法是使用宏。这些宏在常用宏页面上进行了描述。例如，要链接到 HTML 元素的参考页面，请使用 HTMLElement 宏；要链接到 CSS 属性的参考页面，请使用 CSSxRef 宏。

我们遵循类似的交叉引用指南，在参考页面、词汇表页面和指南的末尾的另请参阅部分。

外部链接

MDN Web 文档允许在特定情况下使用外部链接。请使用本节中描述的指南来决定是否可以在 MDN Web 文档中包含外部链接。如果不遵循这些指南，添加外部链接的拉取请求将被拒绝。

如果您正在考虑向 MDN 的学习 Web 开发内容添加外部链接，请同时阅读学习 Web 开发编写指南 > 合作伙伴链接和嵌入。

通常，如果您正在考虑添加外部链接，您需要确保以下风险最小

• 失效或过时的链接
• 出现认可迹象，特别是商业产品或服务
• 试图利用 MDN Web 文档分发垃圾邮件
• 模糊链接目标的短链接

• 好的外部链接：好的外部链接将读者引导至相关、持久且广受信赖的资源。您应优先添加指向以下外部内容的链接

  • 独特或不可或缺（例如，IETF RFC）
  • 归因、引用或致谢所必需（例如，作为知识共享署名的一部分）
  • 与在 MDN Web Docs 本身中包含此类内容相比，更可能针对该主题进行维护（例如，供应商的发行说明）
  • 开源或社区驱动，如 MDN Web Docs 本身

• 不良外部链接：不良外部链接缺乏相关性、可维护性、可访问性，或以其他方式对读者设置障碍。避免添加指向以下外部内容的链接

  • 通用或不具体（例如，供应商主页，而不是相关文档）
  • 短暂或未维护（例如，一次性公告）
  • 自链接或自推广（例如，作者在 MDN Web Docs 之外的作品）
  • 需要付费（例如，超出业余爱好者、学生或低收入国家读者能力的昂贵课程）
  • 无法访问（例如，没有字幕的视频）

• 自推广或垃圾邮件链接：虽然个人博客文章、会议演讲或 GitHub 存储库具有价值，但链接到您自己的资源可能会产生利益冲突的表象。在链接到您有业务或个人关系的资源之前，请三思。

  注意： 如果您与链接目标存在业务或个人关系，您必须在拉取请求中披露该关系。未能这样做可能会危及您继续参与 MDN Web 文档。

  有时此类链接是相关且适当的。例如，如果您是某个规范的编辑，并且正在为与该规范相关的文档做出贡献，那么链接到该规范是预期且可接受的。但您必须披露您与链接之间的关系。

缩短的 URL（短链接）

URL 缩短器（例如 TinyURL 或 Bitly）非常适合将长链接缩短为短小、易于记忆的 URL（也称为“短链接”）。然而，它们也模糊了 URL 的目的地。此外，对于某些缩短器，目的地可以在创建后更改，此功能可用于恶意目的。

不要使用通过第三方（用户可生成）URL 缩短器创建的链接。例如，如果 https://myshort.link/foobar 是由随机用户生成的短 URL，并重定向到 https://example.com/somelongURL/details/show?page_id=foobar，则使用较长的 example.com URL。

另一方面，鼓励使用由维护目标 URL 的组织维护的第一方缩短器。https://bugzil.la 由 Mozilla 拥有和运营，是一个 URL 缩短器，重定向到 https://bugzilla.mozilla.org/，后者也是 Mozilla 拥有的域名。在这种情况下，请使用较短的 URL。例如，使用 https://bugzil.la/1682349 而不是 https://bugzilla.mozilla.org/show_bug.cgi?id=1682349。

标题级别

当新段落开始一个新部分时，应添加标题。按递减顺序使用这些 markdown 标题级别，不要跳过级别：##，然后是 ###，然后是 ####；它们分别转换为 HTML 标题标签 <h2>、<h3> 和 <h4> 标签。

## 是允许的最高级别，因为 # 保留用于页面标题。我们建议标题级别不要超过三级。如果您觉得需要添加第四级标题，请考虑将文章分解为几个带有登陆页面的较小文章。或者，考虑将信息作为项目符号列表呈现，以避免使用四级标题。

在创建小节标题时，请记住以下注意事项

• 不要创建单个子节。 不要将一个主题细分为一个子主题。要么是两个或更多子标题，要么一个都没有。
• 不要在标题中使用内联样式、类或宏。 但是，您可以使用反引号来指示代码术语（例如，“使用 FooBar 接口”）。
• 不要创建“撞头”标题。 它们是指紧跟在子标题之后的标题，它们之间没有内容文本。这看起来不好，并且使读者在外部部分的开头没有任何解释性文本。

图像及其他媒体

如果您在页面中包含图像或其他媒体，请遵循以下指南

• 确保媒体许可证允许您使用它们。尽量使用具有非常宽松的许可证（例如 CC0）或至少与我们通用内容许可证 (知识共享署名-相同方式共享许可证 (CC-BY-SA)) 兼容的媒体。
• 对于图像，请通过 https://tinypng.com 或 https://imageoptim.com 运行它们以减小页面重量。
• 对于 SVG，请通过 SVGOMG 运行代码，并确保 SVG 文件末尾有一个空行。
• 每张图片都必须包含描述性 alt 文本。

列表

列表应在所有页面上保持一致的格式和结构。单个列表项应使用适当的标点符号书写，无论列表格式如何。但是，根据您正在创建的列表类型，您需要调整您的写作，如下面几节所述。在这两种情况下，都应包含一个引导句来描述列表中的信息。

• 项目符号列表：项目符号列表应用于将相关的简洁信息分组。列表中的每个项目应遵循相似的句子结构。项目符号列表中的句子和短语（即，缺少动词或主语或两者兼有的句子片段）应包含标准标点符号——句子以句号结尾，短语则不以句号结尾。

  如果列表项中有多个句子，则每个句子末尾必须出现句号，包括该项的最后一个句子，就像段落中预期的一样。这是一个正确结构的项目符号列表的示例

  在这个例子中，我们应该包含

  • 一个条件，并附有简要解释。
  • 一个类似的条件，并附有简要解释。
  • 另一个条件，并附有进一步解释。

  请注意，相同的句子结构在每个项目符号之间重复。在此示例中，每个项目符号都说明了一个条件，后跟逗号和简要解释，并且列表中的每个项目都以句号结尾。

  如果列表项包含不完整的句子，则末尾不需要句号。例如

  以下与颜色相关的属性在此场景中将很有帮助

  • propertyA: 设置背景颜色
  • propertyB: 为文本添加阴影

  如果一个或多个列表项是完整的句子，则在每个列表项之后使用句号，即使列表项包含三个或更少的单词。但是，尽可能地，所有列表项遵循相同的结构；确保所有列表项都是完整的句子或短语。

• 编号列表：编号列表主要用于枚举一组指令中的步骤。由于指令可能很复杂，因此清晰度至关重要，特别是当每个列表项中的文本很长时。与项目符号列表一样，遵循标准标点符号用法。这是一个正确结构的编号列表的示例

  为了正确构建编号列表，您应该

  1. 以标题或简短段落开头，以介绍说明。在开始说明之前，向用户提供上下文很重要。
  2. 开始创建您的说明，并将每个步骤保存在其自己的编号项中。您的说明可能非常广泛，因此清晰书写和使用正确的标点符号非常重要。
  3. 完成说明后，在编号列表后附上一个简短的总结或解释，说明完成后的预期结果。

  以下是为前面列表编写结束语的示例

  我们创建了一个简短的编号列表，提供了生成格式正确的编号列表的指导步骤。

  请注意，编号列表中的项目读起来像短段落。由于编号列表通常用于指导目的或引导某人完成有序过程，因此请确保每个项目都重点突出：每个步骤一个编号项目。

另请参阅部分

MDN Web Docs 上的大多数指南、参考页面甚至词汇表页面都在文章末尾包含一个“另请参阅”部分。本节包含 MDN 内部相关主题的交叉引用，有时还包含指向相关外部文章的链接。例如，这是 @layer 页面的另请参阅部分。

通常，“另请参阅”部分中的链接以项目符号列表格式呈现，列表中的每个项目都是一个短语。然而，在 MDN 的学习 Web 开发部分，“另请参阅”部分遵循定义列表格式。

为了保持 MDN Web Docs 的一致性，在添加或更新“另请参阅”部分时，请牢记以下指南。

链接文本

• 链接文本应与链接页面的标题或部分标题相同。例如，链接到此 ARIA 页面（页面标题为“ARIA states and properties”）的链接文本将是
  • 正确：ARIA states and properties
• 即使链接文本与链接页面的标题或部分标题不同，也应使用句子大小写。页面或部分标题中使用的字母大小写可能不正确。例如，指向怪异模式页面的链接文本（正确句子大小写）将是
  • 正确：Quirks mode
• 对于外部链接，即使目标文章页面的大小写不同，也请使用句子大小写。这是为了确保 MDN Web Docs 的一致性。书籍名称除外。
• 在 MDN 上，您可以选择使用宏链接到页面，如常用宏页面上的链接到参考页面部分所述。使用宏将为链接文本中的关键字添加代码格式，如下一个示例所示。
• 链接列表项开头不需要冠词（“A”、“An”、“The”）。列表项末尾不需要标点符号，因为它始终是一个术语或短语。
  • 正确：revert-layer
  • 不正确：The revert-layer keyword.
  • 正确：HTML DOM API
  • 不正确：The HTML DOM API
• 如前面的示例所示，使用反引号（`）为链接文本中的关键字和字面量添加代码格式，即使该格式未在页面和部分标题中使用。例如，对于页面标题“Array() constructor”，链接文本将是 Array() constructor。

描述性文本

• 围绕链接的描述性文本应保持最少。如果需要描述，请在链接文本和冒号后添加。描述应措辞为短语，不带结尾标点符号。所有链接文本应置于开头，以方便快速浏览链接列表。
  • 正确：:checked, :indeterminate: 用于样式化复选框的 CSS 选择器
• 在系列中最后一个项目之前不要使用连词“and”。
  • 正确：background-color, border-color, color, caret-color, column-rule-color, outline-color, text-decoration-color, text-emphasis-color, text-shadow: 其他与颜色相关的属性
• 对于外部链接，在可行和适当的情况下，应尽可能注明来源网站和出版或最后更新年份（在括号中）。提前提供这些信息可以使读者清楚地了解点击链接后将到达的目的地。出版或最后更新日期有助于读者评估链接文章的相关性，也有助于 MDN 维护人员审查长时间未更新的文章链接。例如，如果您提供维基百科文章的链接，则可以忽略出版/更新日期。以下列表项是“另请参阅”部分中添加指向 Top-level await 外部文章的链接的示例，以及来源和年份信息
  • 正确：v8.dev 上的顶层 await (2019)
• 对于书籍的外部链接，您还可以提供作者姓名。一些示例列在延伸阅读部分。请不要为您可能链接的博客文章或 GitHub 存储库添加作者姓名。

链接顺序

• 按以下顺序列出指向 MDN 页面的链接：首先是参考页面，然后是相关指南和教程页面的链接。此建议顺序主要是为了帮助列表中的项目易于扫描。
• 如果列表是内部链接和外部链接的混合，请首先列出内部链接，然后是外部链接。
• 在内部和外部链接的每个组中，遵循字母顺序或从简单到高级的顺序，以对上下文最有意义的方式。

子页面

当您需要添加有关某个主题或主题领域的文章时，通常会通过创建登陆页面，然后为每个单独的文章添加子页面来实现。登陆页面应以一两个段落描述该主题或技术开头，然后提供子页面列表，并附上每个页面的描述。您可以使用我们创建的一些宏将页面自动插入到列表中。

例如，考虑JavaScript指南，其结构如下

• JavaScript/Guide – 主要目录页面
• JavaScript/Guide/JavaScript 概述
• JavaScript/Guide/函数
• JavaScript/Guide/对象模型详情

尽量避免将您的文章放在层次结构的顶部，这会减慢网站速度，并降低搜索和网站导航的效率。

短链接（slug）

页面标题显示在页面顶部，可能与页面“slug”（URL 中 <locale>/docs/ 后面的部分）不同。在定义 slug 时，请牢记以下准则

• 短链接应该保持简短。创建新的层级时，新层级在短链接中的组成部分应该只有一两个单词。
• 短链接应使用下划线分隔多词组件，例如 /en-US/docs/Learn_web_development/Core/Structuring_content/Basic_HTML_syntax 中的 Basic_HTML_syntax。
• 在短链接中，每个组件也应遵循句子式大小写，例如前面示例中的 Basic_HTML_syntax。

标题

页面标题用于搜索结果，也用于在页面顶部的面包屑列表中构建页面层次结构。页面标题可能与页面“短链接”不同，如短链接部分所述。

撰写标题时，请牢记以下准则

• 大写风格：在 MDN Web Docs 上，页面标题和部分标题应使用句子式大写（只大写第一个单词和专有名词），而不是标题式大写

  • 正确：“A new method for creating JavaScript rollovers”
  • 不正确：“A New Method for Creating JavaScript Rollovers”

  我们有许多旧页面是在此样式规则制定之前编写的。如果您愿意，请随意根据需要更新它们。我们正在逐步处理它们。

• 通用指南：决定要记录什么以及如何组织内容是写作的第一步。编写目录可以帮助您决定如何组织信息。先涵盖简单的概念，然后转向更复杂和高级的概念。先涵盖概念性信息，然后转向以行动为导向的主题。

  编写页面和部分或小节标题时，请牢记以下准则

  • 从高到低：如标题级别部分所述，从高 ## 到低 ####，不要跳过级别。使用更高级别的标题表示更广泛的介绍性标题，并随着向更低级别标题的进展使用更具体的标题。
  • 逻辑分组：确保所有相关的子节都在一个更高级别的标题下逻辑分组。命名各个部分的标题可以帮助您完成此练习。
  • 保持标题简短：较短的标题更容易在文本和目录中扫描。
  • 保持标题具体：使用标题来传达该部分将涵盖的具体信息。例如，对于介绍 HTML 元素的部分，使用标题“HTML 元素”而不是“介绍”或“概述”。
  • 保持标题集中：使用标题传达一个目标——一个将在该部分中涵盖的单一思想或概念。为此，尽可能地，尽量不要在标题中使用连词“and”。
  • 使用平行结构：在同一标题级别使用相似的语言。例如，如果 ### 标题级别标题使用动名词（即以“-ing”结尾的词语，例如“Installing”），那么请尝试在该标题级别使用动名词编写所有标题。如果标题以祈使动词开头，例如“Use”、“Configure”，那么请在该标题级别以祈使动词开头编写所有标题。
  • 避免在低级标题中出现通用术语：不要在低级标题中重复高级标题中的文本。例如，在名为“逗号”的部分中，将子节标题命名为“介绍性从句之后”而不是“介绍性从句之后的逗号”。
  • 不要以冠词开头：避免标题以冠词“a”、“an”或“the”开头。
  • 添加引导信息：在标题之后，添加一些介绍性文本来解释该部分将涵盖的内容。

另见

• 编写代码示例的指南
• 编写 HTML 代码示例的指南
• 编写 CSS 代码示例的指南
• 编写 JavaScript 代码示例的指南
• 编写 shell 提示符代码示例的指南

延伸阅读

其他样式指南

如果您对本指南未涵盖的用法和样式有疑问，我们建议参考 Microsoft 写作风格指南 或 芝加哥风格手册。

语言、语法和拼写

如果您有兴趣提高写作和编辑技能，以下资源可能会有所帮助。

• brians.wsu.edu 上的常见英语用法错误
• alt-usage-english.org 上的英语语法常见问题
• english.stackexchange.com 上的英语语言和用法：英语语言用法问答网站
• google.com/books 上的《Merriam-Webster's Concise Dictionary of English Usage》（2002 年出版）：学术但用户友好的循证建议；非常适合非母语人士，特别是介词用法
• harpercollins.com 上的 William Zinsser 的《On Writing Well》（2016 年出版）
• google.com/books 上的 Joseph Williams 和 Gregory Colomb 的《Style: Lessons in Clarity and Grace》（2019 年出版）