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.

Before editing a page, identify who owns its content:

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:

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

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.

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.

export default {
  mode: 'development',
};

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

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

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

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

Install dependencies and generate the site:

npm install
npm run build

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

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.