Writer's Guide

The following sections contain all you need to know about editing and formatting the content within this site. Make sure to do some research before starting your edits or additions. Sometimes the toughest part is finding where the content should live and determining whether or not it already exists.

Process

1. Check related issue if an article links to one.
2. Hit edit and expand on the structure.
3. PR changes.

YAML Frontmatter

Each article contains a small section at the top written in 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]
---

Let's break these down:

• title: The name of the article.
• group: The name of the sub-section
• sort: The order of the article within its section (or) sub-section if it is present.
• contributors: A list of GitHub usernames who have contributed to this article.
• related: Any related reading or useful examples.

Note that related will generate a Further Reading section at the bottom of the page and contributors will yield a Contributors section below it. If you edit an article and would like recognition, don't hesitate to add your GitHub username to the contributors list.

Article Structure

1. Brief Introduction - a paragraph or two so you get the basic idea about the what and why.
2. Outline Remaining Content – how the content will be presented.
3. Main Content - tell what you promised to tell.
4. Conclusion - tell what you told and recap the main points.

Typesetting

• Webpack can be written with a capital W at the beginning of a sentence. (source)
• loaders are enclosed in backticks and kebab-cased: sass-loader, ts-loader, …
• plugins are enclosed in backticks and camel-cased: BannerPlugin, NpmInstallWebpackPlugin, …
• Use "webpack 2" to refer to a specific webpack version ("webpack v2")
• Use ES5; ES2015, ES2016, … to refer to the ECMAScript standards (ES6, ES7)

Formatting

Code

Syntax: ```js … ```

function foo() {
  return "bar";
}

foo();

Quotation

Use single quotes in code snippets and project files (.jsx, .scss etc):

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

And in inline backticks:

correct

Set value to 'index.md'...

incorrect

Set value to "index.md"...

Lists

• Boo
• Foo
• Zoo

Lists should be ordered alphabetically.

Tables

Tables should also be ordered alphabetically.

Configuration Properties

The configuration properties should be ordered alphabetically as well:

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

Quotes

Blockquote

Syntax: >

This is a blockquote.

Tip

Syntax: T>

Syntax: W>

Syntax: ?>

Assumptions and simplicity

Do not make assumptions when writing the documentation.

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

Please do not assume things are simple. Avoid words like 'just', 'simply'.

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

Configuration defaults and types

Always provide types and defaults to all of the documentation options in order to keep the documentation accessible and well-written. Types are written in TypeScript notation, placed directly under the documented option's title:

configuration.example.option

'none' | 'development' | 'production' = 'none'

The type comes first and the default, where there is one, follows after =. TypeScript has no syntax for a default value, so that trailing = value is the one addition this site makes to it — everything to its left is ordinary TypeScript that a reader can paste into an editor.

Use a space between separate annotations to list alternatives that are easier to read apart than a single union:

'none' | 'development' | 'production' = 'none' boolean

Arrays, functions, objects and records are written as TypeScript spells them:

Mark an optional property with ?, as TypeScript does, rather than describing it in prose.

When an option has different defaults depending on the mode, use a defaults table instead of the inline = value syntax:

configuration.example.option

'natural' | 'named' | 'deterministic'

The default value of configuration.example.option depends on the mode:

If an option has a boolean default that varies by mode:

configuration.example.flag

boolean

The default value of configuration.example.flag depends on the mode:

Options shortlists and their typing

Sometimes, we want to describe certain properties of objects and functions in lists. When applicable add typing directly to the list where properties are enlisted, in the same TypeScript notation:

• madeUp (boolean = true): short description
• shortText (string = 'i am text'): another short description
• pattern (RegExp | string): a property with no default

An example can be found on the options section of the EvalSourceMapDevToolPlugin's page.

Adding links

Please use relative URLs (such as /concepts/mode/) to link our own content instead of absolute URLs (such as https://webpack.js.org/concepts/mode/).