title: 文档写作指南
sort: 1
contributors:

• pranshuchittora
• EugeneHlushko
• shivxmsharma

文档写作指南

以下部分包含你编辑和格式化本站内容所需了解的所有信息。在开始编辑或添加内容之前，请务必进行一些研究。有时最难的部分是找到内容应该放在哪里，以及确定它是否已经存在。

流程

1. 如果文章链接到某个关联 issue，请检查该 issue。
2. 点击 edit，在现有结构上展开。
3. 提交 PR 更改。

YAML Frontmatter

每篇文章顶部都包含一小段用 YAML Frontmatter 编写的内容：

---
title: My Article
group: My Sub-Section
sort: 3
contributors:
  - [github username]
related:
  - title: Title of Related Article
    url: [url of related article]
---

让我们逐项拆解：

• title：文章的名称。
• group：子部分的名称。
• sort：文章在其所在章节（或子部分，如果存在）中的排序。
• contributors：为这篇文章做出贡献的 GitHub 用户名列表。
• related：任何相关的阅读材料或有用的示例。

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

文章结构

1. 简要介绍——一两段话，让你对“是什么”和“为什么”有基本的了解。
2. 概述剩余内容——内容将如何呈现。
3. 主要内容——讲述你承诺要讲述的内容。
4. 结论——总结你讲述的内容并回顾要点。

排版

• 在句首时，webpack 可以写作首字母大写的 Webpack（来源）。
• loader 使用反引号包裹，并采用 kebab-case 命名：css-loader、ts-loader、……
• 插件使用反引号包裹，并采用 camel-case 命名：BannerPlugin、NpmInstallWebpackPlugin、……
• 使用 "webpack 2" 来指代特定的 webpack 版本（"webpack v2"）
• 使用 ES5、ES2015、ES2016……来指代 ECMAScript 标准（ES6、ES7）

格式规范

代码

语法：```js … ```

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

引用

块引用

语法：>

这是一个块引用。

提示（Tip）

语法：T>

T> 这是一个提示。

语法：W>

W> 这是一个警告。

语法：?>

?> 这是一个待办。

假设与简洁

编写文档时不要做假设。

- You might already know how to optimize bundle for production...
+ As we've learned in [production guide](/guides/production/)...

请不要把事情想得过于简单。避免使用 "just"、"simply" 之类的词。

- Simply run command...
+ Run the `command-name` command...

配置默认值和类型

始终为所有文档选项提供类型和默认值，以保持文档易于理解且编写良好。我们会在为文档选项命名后附加类型和默认值：

configuration.example.option

string = 'none'

其中 = 'none' 表示该选项的默认值为 'none'。

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

其中 : 'none' | 'development' | 'production' 列举了可能的类型值，在这种情况下，三个字符串是可接受的：'none'、'development' 和 'production'。

使用空格分隔类型，以列出该选项所有可用的类型：

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

要标记数组，请使用方括号：

string [string]

如果 array 中允许多种类型，请使用逗号：

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

要标记函数，请在可用时也列出参数：

function (compilation, module, path) => boolean

其中 (compilation, module, path) 列出了所提供的函数将接收的参数，=> boolean 表示函数的返回值必须是 boolean。

要将 Plugin 标记为可用的选项值类型，请使用 Plugin 的驼峰式名称：

MinimizerPlugin [MinimizerPlugin]

这意味着该选项期望一个或几个 MinimizerPlugin 实例。

要标记数字，请使用 number：

number = 15: 5, 15, 30

要标记对象，请使用 object：

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

当对象的键可以有多种类型时，使用 | 列出它们。这里有一个例子，其中 prop1 既可以是字符串，也可以是字符串数组：

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

这使我们能够显示默认值、枚举和其他信息。

当选项的默认值取决于 mode 时，请使用默认值表格，而不是内联的 = value 语法：

configuration.example.option

string: 'natural' | 'named' | 'deterministic'

configuration.example.option 的默认值取决于 mode：

如果选项的布尔默认值随模式变化：

configuration.example.flag

boolean

configuration.example.flag 的默认值取决于 mode：

如果对象的键是动态的、由用户定义的，请使用 <key> 来描述它：

object = { <key> string }

选项简要列表及其类型标注

有时，我们想在列表和函数中描述对象的某些属性。在适用的情况下，直接在列举属性的列表中添加类型标注：

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

警告：这里的 : 并不是必需的，注意属性、类型和默认值的写法。

可以在 EvalSourceMapDevToolPlugin 页面的 options 部分 找到一个例子。

添加链接

请使用相对 URL（例如 /concepts/mode/）来链接我们自己的内容，而不是绝对 URL（例如 https://webpack.js.org/concepts/mode/）。