作者指南

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

流程

1. 如果文章链接到某个问题，请查看相关问题。
2. 点击“编辑”并扩展结构。
3. PR 更改。

YAML 前置信息

每篇文章顶部都包含一小节，用 YAML 前置信息 编写。

---
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 将在页面底部生成一个“进一步阅读”部分，而 contributors 将在下面生成一个“贡献者”部分。如果您编辑了文章并希望获得认可，请随时将您的 GitHub 用户名添加到 contributors 列表中。

文章结构

1. 简要介绍 - 一两段文字，让你了解基本的概念和目的。
2. 剩余内容概述 - 内容的呈现方式。
3. 主要内容 - 讲述你承诺要讲述的内容。
4. 结论 - 总结你讲述的内容，并概括主要要点。

排版

• Webpack 在句首可以写成大写的 W。 (来源)
• 加载器用反引号括起来，并使用 短横线连接：css-loader, ts-loader, …
• 插件用反引号括起来，并使用 驼峰命名法：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>

语法: ?>

假设和简洁性

编写文档时不要做假设。

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

请不要假设事情很简单。避免使用“仅仅”、“简单”之类的词语。

- 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的驼峰式标题

TerserPlugin [TerserPlugin]

这意味着该选项需要一个或多个TerserPlugin实例。

要标记数字，请使用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]}

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

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

object = { <key> string }

选项简表及其类型

有时，我们希望在列表中描述对象和函数的某些属性。在适用情况下，将类型直接添加到列出属性的列表中

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

可以在 options 部分的 EvalSourceMapDevToolPlugin 页面 上找到示例。

添加链接

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