作者指引

以下部分包含编辑和格式化本网站内容的所有必需知识。请确保在开始编辑或添加之前，你已经进行过一些研究。有时候最困难的地方在于，确定内容应该在哪和确定它是否存在。

步骤

1. 如果文章包含 issue 链接，先查看 issue。
2. 点击编辑并阐述结构。
3. 提交 PR 修改。

YAML 文件顶部信息

每篇文章的顶部都包含一小部分 YAML Frontmatter 格式的内容：

---
title: 我的文章
group: 我的小节
sort: 3
contributors:
  - [github 用户名]
related:
  - title: 相关文章的标题
    url: [相关文章的 url]
---

让我们来逐个分析：

• title：文章的名称。
• group：小节的名称。
• sort：这篇文章在此类（或子类）中的顺序（如果存在同类）。
• contributors：文章贡献者的 GitHub 用户名列表。
• related：任何相关阅读或有用示例。

请注意，related 将在页面底部生成 Further Reading 部分，contributors 将在其下生成 Contributors 部分。如果你编辑了一篇文章，并希望获得认可，请不要犹豫，将你的 GitHub 用户名添加到 contributors 列表中。

文章结构

1. 简介 —— 一两个段落，以便你了解关于什么和为什么的基本想法。
2. 概述剩余内容 —— 将如何呈现内容。
3. 主要内容 —— 讲述你承诺要讲的内容。
4. 结论 —— 讲述你讲了什么并复述要点。

排版

• Webpack 作为句子的第一个单词时，W 可以大写。参考 source 以了解更多。
• loader 应当用反引号包裹，并且使用 kebab-cased：css-loader，ts-loader，……
• plugin 应当用反引号包裹，并且使用 camel-cased: BannerPlugin， NpmInstallWebpackPlugin，……
• 使用 "webpack 2" 指代特定的 webpack 版本 ("webpack v2")
• 使用 ES5; ES2015, ES2016, …… 指代 ECMAScript 标准 (ES6, ES7)

译者注：中文文档排版规范不必依照于此。

格式化

代码

语法：```javascript … ```

function foo() {
  return 'bar';
}

foo();

引号

在代码片段和项目文件中使用单引号 (.jsx， .scss 等)：

- import webpack from "webpack";
+ import webpack from 'webpack';

行内反引号也是一样：

正确

把值设置为 'index.md'……

错误

把值设置为 "index.md"……

列表

• Boo
• Foo
• Zoo

列表应该按字母顺序排序。

表格

表格也应该按字母顺序排序。

配置属性

配置 属性，应该按字母顺序排序：

• devServer.compress
• devServer.hot
• devServer.static

引用

引用块

语法：>

这是一个引用块。

提示

语法：T>

语法：W>

语法：?>

假设与详略

写文档时，不要做假设：

- 你可能已经知道如何为生产环境优化 bundle ……
+ 我们在 [production guide](/guides/production/) 学习过……

请不要假设事情简单。避免使用词汇“只是”，“简单地”。

- 简单地运行命令……
+ 运行 `command-name` 命令……

配置的默认值和类型

总是为所有文档选项提供类型和默认值，以保持文档的可读性和良好书写。我们在选项后面加上类型和默认值：

configuration.example.option

string = 'none'

这里 = 'none' 表示指定选项的默认值是 'none' 。

string = 'none': 'none' | 'development' | 'production'

这里 : 'none' | 'development' | 'production' 枚举所有可能的类型值，本例接受 3 个字符串：'none', 'development' 和 'production'。

在类型之间使用空格，为指定选项列举所有可用的类型：

string = 'none': 'none' | 'development' | 'production' boolean

使用方括号表示数组：

string [string]

如果 数组 允许多种类型，使用英文逗号：

string [string, RegExp, function(arg) => string]

标记为函数时，如果有参数，应同时把参数列出来：

function (compilation, module, path) => boolean

这里 (compilation, module, path) 列举指定函数接受的参数，=> boolean 表示函数返回值的类型必须是 boolean。

标记 Plugin 为可用的选项值类型时，使用 Plugin 的 camel case 标题：

TerserPlugin [TerserPlugin]

这表示选项接受一个或多个 TerserPlugin 实例。

使用 number 标记为 number ：

number = 15: 5, 15, 30

使用 object 标记为对象：

object = { prop1 string = 'none': 'none' | 'development' | 'production', prop2 boolean = false, prop3 function (module) => string }

当对象的 key 可以有多个类型时，用 | 列来出。如下例子，prop1 可以是字符串或字符串数组：

object = { prop1 string = 'none': 'none' | 'development' | 'production' | [string]}

这样我们可以展示默认值，枚举和其他信息。

如果对象的 key 是动态的，用户自定义的，用 <key> 来描述：

object = { <key> string }

选项 shortlist 及其类型

有时，我们希望描述对象的某些属性，以及列表中的函数。在属性列表直接添加即可：

• madeUp (boolean = true): 简短描述
• shortText (string = 'i am text'): 另一个简短描述

EvalSourceMapDevToolPlugin 页面的 选项 部分 有一个例子。

添加链接

请使用相对 URL (如 /concepts/mode/) 来链接到自有内容，不要用绝对 URL (如 https://webpack.js.org/concepts/mode/)。