Writing guidelines

MDN Web Docs is an open-source project. The sections outlined below describe our guidelines for what we document and how we do it on MDN Web Docs. To learn about how to contribute, see our contribution guidelines.

What we write

This section covers what we include on MDN Web Docs and want we don't, as well as a number of other policies, such as when we write about new technologies, the content suggestion process, and whether we accept external links. This is a good place to start if you're considering writing or updating content for us. This section also includes:

Inclusion criteria

It provides an in-depth criteria for content to be included on MDN Web Docs, the application process for getting new documentation added on MDN Web Docs, and the expectations and guidelines for a party applying.

How to write for MDN Web Docs

This section covers all the information for creating and editing pages, including certain processes and techniques we adhere to. This section provides information about getting started, a general overview into how pages are structured, and where to find how-tos on specific tasks. This section includes topics such as:

Using markdown

The markdown format we use derives from GitHub flavored markdown (GFM). This section is a guide to the markdown we use on MDN Web Docs, including formats for specific in-page components, such as notes and definition lists.

Adding images and media

This section describes the requirements for including media in pages, such as images.

Adding an entry to the glossary

This section explains how to add and link to entries in the MDN Web Docs glossary. It also provides guidelines about glossary entry layout and content.

How to research a technology

This section provides some handy tips for researching a technology you are documenting.

How to move and delete pages

This section explains how to move or delete a page.

Our writing style guide

The writing style guide covers the language and style we use to write on MDN Web Docs. It also covers how to format code examples.

Page types on MDN Web Docs

Each page on MDN Web Docs has a specific page type, whether that's a CSS reference page or a JavaScript guide page. This section lists the different page types and provides templates for each type. It's a good idea to browse these to understand which page type you are writing.

Page structures on MDN Web Docs

This section covers the various page structures that we use to provide consistent presentation of information on MDN Web Docs. This includes:

Code examples

There are a lot of different ways to include code examples on pages. This section outlines them and provides syntax guidelines for the different languages.


Macros are shortcuts that are used in pages to generate content, such as sidebars. This section lists the macros we use and what they do.

How to label a technology

This section covers our definitions for the terms obsolete, deprecated, and experimental and provides guidelines on when we remove content from MDN Web Docs.

This section describes what copyright license content is and how to attribute correctly.