Documentation Contributions - Gutenberg Block Editor

This guide explains how to contribute to Gutenberg’s documentation, including the block editor handbook and developer documentation.

Getting Started

Documentation for Gutenberg consists of markdown files in the /docs/ directory of the repository and generated documentation from packages. Your contributions help developers understand and work with the block editor.

Community

Join Slack

Connect with the documentation community in the #docs channel on Make WordPress Slack (free to join).

Attend Meetings

Weekly documentation team meetings are held on Tuesdays at 14:00 UTC in the #docs Slack channel.

Follow the Blog

Stay updated with the Make WordPress Docs blog for announcements, meeting notes, and documentation priorities.

Find Documentation Issues

Browse issues with the documentation label to find documentation tasks to work on.

Documentation Types

Gutenberg has two major sets of documentation:

User Documentation

Information for authors publishing posts using the block editor

Block Editor Handbook

Developer documentation for developing, extending, and contributing to Gutenberg

This guide covers contributing to the block editor handbook. For user documentation, follow the docs blog or ask in the #docs Slack channel.

Documentation Publishing

The block editor handbook is automatically published from the Gutenberg repository:

Documentation source: /docs/ directory in Gutenberg repository
Published to: Block Editor Handbook
Publishing frequency: Every 15 minutes (automated)

Handbook Structure

The handbook is organized into four functional sections:

Getting Started Tutorials

Complete lessons that guide learners step-by-step through achieving specific objectives.Example: Create a Block Tutorial

How-To Guides

Short, focused lessons for completing specific tasks quickly.Example: How to Add a Button to the Block Toolbar

Reference Guides

API documentation and purely functional descriptions of components, hooks, and packages.

Explanations

Longer documentation focused on learning and understanding concepts, not specific tasks.

This structure is based on The Documentation System, which explains the needs and functions of each documentation type.

Contributing Workflow

Update an Existing Document

Clone the Repository

Follow the Git Workflow guide to fork and clone the Gutenberg repository.

Create a Branch

Create a new branch for your documentation changes:

git switch -c docs/update-contrib-guide

Make Changes

Edit the existing markdown file using your preferred editor. Follow the copy guidelines.

Commit Changes

Commit your changes with a descriptive message:

git commit -m "Docs: Update contributing guide with new workflow"

Create Pull Request

Push your branch and create a pull request with the [Type] Developer Documentation label.

Create a New Document

Creating new documentation requires a working JavaScript development environment to build the documentation files.

Create Markdown File

Create a new .md file in the appropriate /docs/ subdirectory. Use lowercase, dashes for spaces, and .md extension.

# Example
touch docs/how-to-guides/my-new-guide.md

Add Content

Write your documentation using markdown notation. Every document requires one and only one h1 tag.

# My New Guide

This guide explains how to...

Update Table of Contents

Add an entry to docs/toc.json in the appropriate hierarchy:

{
  "title": "My New Guide",
  "slug": "my-new-guide",
  "markdown_source": "../docs/how-to-guides/my-new-guide.md",
  "parent": "how-to-guides"
}

Build Documentation

Run the documentation build to update manifest.json:

npm run docs:build

Commit All Files

Commit both your new markdown file and the updated manifest.json:

git add docs/how-to-guides/my-new-guide.md docs/toc.json docs/manifest.json
git commit -m "Docs: Add guide for new feature"

If you forget to run npm run docs:build, your PR will fail the static analysis check because manifest.json will have uncommitted changes.

Writing Guidelines

Using Templates

Use the how-to guide template for consistent structure:

Copy the markdown from the template
Fill in your content following the structure
See The Good Docs Project for additional templates

Creating Links

Documentation can be browsed in multiple contexts (handbook, GitHub, npm), so use absolute path links without the GitHub prefix:

/docs/contributors/code/getting-started.md
/packages/components/README.md
/packages/components/src/button/README.md

https://github.com/WordPress/gutenberg/blob/trunk/docs/...
../getting-started.md
README.md

Use the full directory and filename from the repository, not the published URL. The handbook creates short URLs automatically.

Code Examples

Wrap code examples in triple backticks with a language specifier:

```javascript
const example = 'Hello World';
console.log( example );
```

Code Tabs for JSX and Plain JavaScript

Use codetabs to show both JSX and plain JavaScript versions:

{% codetabs %}
{% JSX %}
```jsx
import { Button } from '@wordpress/components';

function MyButton() {
    return <Button variant="primary">Click me</Button>;
}
```
{% Plain %}
```js
const { Button } = wp.components;

function MyButton() {
    return wp.element.createElement(
        Button,
        { variant: 'primary' },
        'Click me'
    );
}
```
{% end %}

JSX is the preferred format and should be shown first as the default view. Plain JavaScript is recommended for beginner tutorials or short examples.

Callout Notices

Use HTML with callout callout-LEVEL classes for notices:

<div class="callout callout-info">
This is an **info** callout with markdown support.
</div>

<div class="callout callout-tip">
This is a **tip** callout.
</div>

<div class="callout callout-alert">
This is an **alert** callout.
</div>

<div class="callout callout-warning">
This is a **warning** callout.
</div>

In callout notices, links must use HTML <a href=""></a> notation. Markdown link transformation is not applied inside callouts.

Video Embeds

Videos must be hosted on the WordPress YouTube channel as unlisted videos. Contact the #marketing Slack channel for assistance. Once uploaded, embed using:

<iframe 
  width="960" 
  height="540" 
  src="https://www.youtube.com/embed/VIDEO_ID" 
  title="Video Title" 
  frameborder="0" 
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" 
  allowfullscreen="true">
</iframe>

Videos should have a 16:9 aspect ratio and be filmed at the highest resolution possible.

Documenting Packages

Package documentation is auto-generated from README.md files in package roots. For complex packages, you can split documentation into multiple pages:

Create docs Directory

Create a docs/ directory in your package:

mkdir packages/my-package/docs

Add Additional Markdown Files

Create additional .md files in the docs/ directory.

Create toc.json

Add a toc.json file to define the page hierarchy:

[
  {
    "title": "Advanced Usage",
    "slug": "packages-my-package-advanced",
    "markdown_source": "../packages/my-package/docs/advanced.md",
    "parent": "packages-my-package"
  }
]

Set the parent property to nest pages under the main package name in the handbook.

Editor Configuration

Visual Studio Code Setup

Configure VS Code to auto-format markdown with Prettier:

{
  "[markdown]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
  }
}

Create a .vscode/settings.json file in the Gutenberg directory for project-specific settings.

Git Workflow for Documentation

Documentation follows the same Git workflow as code contributions:

# 1. Create a branch
git switch -c docs/my-documentation-update

# 2. Make changes to markdown files
# ...

# 3. Build documentation (if adding new files)
npm run docs:build

# 4. Commit changes
git commit -m "Docs: Update feature documentation"

# 5. Push to your fork
git push -u origin docs/my-documentation-update

# 6. Create pull request with [Type] Developer Documentation label

See the complete Git Workflow guide or watch the video walkthrough.

Style Guidelines

Follow these documentation standards:

Voice: Use active voice and second person (“you”)
Tone: Be clear, concise, and helpful
Formatting: Follow the Copy Guidelines
Style: Reference the WordPress Tone and Voice Guide

Writing Best Practices

Focus on the “why” and “what”, not just the “how”
Use examples to illustrate concepts
Keep paragraphs short and scannable
Use headings to organize content logically
Include code examples that users can copy and test

Documentation Resources

Official Guidelines

External Resources

The Documentation System - Framework for documentation types
The Good Docs Project - Documentation templates
GitHub Markdown Guide

Quick Reference

Common Documentation Tasks

# Build all documentation
npm run docs:build

# Generate API documentation
npm run docs:api-ref

# Generate component documentation  
npm run docs:components

# Generate block library documentation
npm run docs:blocks

# Generate theme.json reference
npm run docs:theme-ref

# Format markdown files
npm run format docs/**/*.md

File Structure

/docs/
├── getting-started/      # Tutorials
├── how-to-guides/        # How-to guides
├── reference-guides/     # API references
├── explanations/         # Conceptual documentation
├── contributors/         # Contributing guides
├── toc.json             # Table of contents
└── manifest.json        # Generated navigation (auto-updated)

Next Steps

Browse Documentation Issues

Find documentation tasks to work on

Git Workflow

Learn the Git workflow for contributions

Watch Tutorial

Video walkthrough of contributing documentation

Copy Guidelines

Review writing style guidelines

​Getting Started

​Community

​Find Documentation Issues

​Documentation Types

User Documentation

Block Editor Handbook

​Documentation Publishing

​Handbook Structure

​Contributing Workflow

​Update an Existing Document

​Create a New Document

​Writing Guidelines

​Using Templates

​Creating Links

​Code Examples

​Code Tabs for JSX and Plain JavaScript

​Callout Notices

​Video Embeds

​Documenting Packages

​Editor Configuration

​Visual Studio Code Setup

​Git Workflow for Documentation

​Style Guidelines

​Writing Best Practices

​Documentation Resources

​Official Guidelines

​External Resources

​Quick Reference

​Common Documentation Tasks

​File Structure

​Next Steps

Browse Documentation Issues

Git Workflow

Watch Tutorial

Copy Guidelines

Getting Started

Community

Find Documentation Issues

Documentation Types

Documentation Publishing

Handbook Structure

Contributing Workflow

Update an Existing Document

Create a New Document

Writing Guidelines

Using Templates

Creating Links

Code Examples

Code Tabs for JSX and Plain JavaScript

Callout Notices

Video Embeds

Documenting Packages

Editor Configuration

Visual Studio Code Setup

Git Workflow for Documentation

Style Guidelines

Writing Best Practices

Documentation Resources

Official Guidelines

External Resources

Quick Reference

Common Documentation Tasks

File Structure

Next Steps