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 should always be written in lower-case letters. Even at the beginning of a sentence. (source)
• loaders are enclosed in backticks and kebab-cased: css-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: ```javascript … ```

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.contentBase
• devServer.hot

Quotes

Blockquote

Syntax: >

This is a blockquote.

Tip

Syntax: T>

This is a tip.

Syntax: W>

This is a warning.

Syntax: ?>

This is a todo.

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...

Contributors

pranshuchittora