---
title: Writer's Guide
authors: avivkeller,alexander-akait
---

# Writer's Guide

This guide explains how to contribute hand-written content to the webpack website. It does not cover API references, loader and plugin references, or governance pages because those are generated from their source repositories.

## Choose the source of truth

Before editing a page, identify who owns its content:

| Content                                 | Source of truth                    | How this site receives it                  |
| --------------------------------------- | ---------------------------------- | ------------------------------------------ |
| Guides and conceptual documentation     | `pages/guides/` in this repository | Written and reviewed here                  |
| webpack API and configuration reference | webpack source, types, and schemas | Generated by `npm run build:md:api`        |
| Loader and plugin reference pages       | Package README files               | Generated by `npm run build:md:readmes`    |
| Governance documentation                | webpack governance files           | Generated by `npm run build:md:governance` |

> [!IMPORTANT]
> Do not edit generated pages under `pages/docs/api/`, `pages/docs/loaders/`, `pages/docs/plugins/`, or `pages/about/governance/`. Make the change in the owning repository and regenerate the site instead.

## Add or edit a guide

Guide pages are Markdown files under `pages/guides/`. Place new content in the section that best matches the reader's task. Prefer expanding an existing page over creating a second page with overlapping material.

Every page starts with YAML frontmatter and an H1 that matches its title:

```md
---
title: Build Performance
authors: github-user,another-user
---

# Build Performance
```

- `title` is the page title displayed by the site.
- `authors` is a comma-separated list of GitHub usernames. Add your username when you make a meaningful contribution.

When adding or moving a page, update `pages/guides/site.json` so it appears in the Guides sidebar. Its `link` must match the page's generated URL: an `index.md` file represents its directory, while any other filename represents a page without a trailing slash.

## Write for the reader's task

Start by saying what the reader will accomplish and why it matters. Put prerequisites before the steps that require them, then organize the page around the work the reader performs.

- Use direct instructions and concrete examples.
- Introduce one idea at a time.
- Explain unfamiliar terms when they first appear.
- Avoid “simple,” “just,” and other language that assumes the reader's experience.
- Use “webpack” in lowercase except at the beginning of a sentence.
- Write loader package names in kebab case, such as `css-loader`.
- Write plugin class names in Pascal case, such as `DefinePlugin`.
- Refer to releases as “webpack 5,” not “webpack v5.”

Use sentence case for headings. Keep the page title as the only H1 and nest later headings without skipping levels.

## Code examples

Examples should be complete enough to understand and focused on the behavior being taught.

- Use fenced code blocks with the correct language.
- Use single quotes in JavaScript examples.
- Use `node:` prefixes for Node.js built-ins.
- Prefer ECMAScript modules in new examples.
- Include filenames with `displayName` when the surrounding text does not make the file clear.
- Use a `diff` block when a reader is changing an existing example.
- Test commands and runnable examples before opening a pull request.

```js displayName="webpack.config.js"
export default {
  mode: 'development',
};
```

## Links

Use root-relative links for pages on this site and full `https://` URLs for external resources:

```md
[Asset Modules](/guides/core-workflows/asset-modules)
[Node.js](https://nodejs.org/)
```

Check links against the generated output, not the old webpack site. Current webpack API links include their version, for example `/docs/api/v5.x/options#mode`.

Do not add a trailing slash to a normal page route. Directory index pages, such as `/guides/contributing/`, are the exception.

## Callouts

Use callouts sparingly for information that should stand apart from the main flow:

```md
> [!TIP]
> Optional advice that helps in a common situation.

> [!IMPORTANT]
> Information the reader needs to succeed.

> [!WARNING]
> A risk or behavior that can cause an incorrect result.
```

Do not use callouts as a substitute for explaining required steps in the main text.

## Preview and verify

Install dependencies and generate the site:

```bash
npm install
npm run build
```

For changes limited to hand-written pages, you can regenerate the HTML after the generated Markdown already exists:

```bash
npm run build:html
```

Before opening a pull request:

1. Read the rendered page from beginning to end.
2. Check every internal and external link you changed.
3. Confirm code samples and commands are accurate.
4. Run `npm run format:check` and `npm run lint`.
5. Keep the pull request focused on one documentation task.