作者指引

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

步骤

  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-casedcss-loaderts-loader,……
  • plugin 应当用反引号包裹,并且使用 camel-cased: BannerPluginNpmInstallWebpackPlugin,……
  • 使用 "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

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

表格

参数解释说明输入类型默认值
--debug把 loader 切换为 debug 模式booleanfalse
--devtool为打包的资源定义 source map 类型string-
--progress打印 compilation 的百分比进度booleanfalse

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

配置属性

配置 属性,应该按字母顺序排序:

  • 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/)。

2 位贡献者

pranshuchittoraEugeneHlushko