Documentation Contributions Edit

A guide on how to get started contributing documentation to the Gutenberg project.

Discussions Discussions

The Make WordPress Docs blog is the primary spot for the latest information around WordPress documentation: including announcements, product goals, meeting notes, meeting agendas, and more.

Real-time discussions for documentation take place in the #docs channel in Make WordPress Slack (registration required). Weekly meetings for the Documentation team are on Mondays at 14:00UTC.

The Gutenberg project uses GitHub for managing code and tracking issues. The main repository is at: https://github.com/WordPress/gutenberg. To find documentation issues to work on, browse issues with documentation label.

Top ↑

Documentation Types Documentation Types

There are two major sets of documentation for the Gutenberg project:

  1. User documentation is information on how to use the Editor as an author publishing posts. For contributing to user docs, follow the docs blog, or ask in the #docs Slack channel, to understand the current priorities.
  2. Block Editor Handbook is everything related to the Gutenberg project including: developing, extending, and—what you are reading right now—contributing specific to Gutenberg.

The rest of this document covers contributing to the Block Editor Handbook.

Top ↑

Block Editor Handbook Process Block Editor Handbook Process

The Block Editor Handbook is a mix of markdown files in the /docs/ directory of the Gutenberg project repository and generated documentation from the packages.

An automated job publishes the docs every 15 minutes to the Block Editor Handbook site.

See the Git Workflow documentation for how to use git to deploy changes using pull requests.

Update a Document Update a Document

To update an existing page:

  1. Check out the gutenberg repository.
  2. Create a branch to work, for example docs/update-contrib-guide.
  3. Make the necessary changes to the existing document.
  4. Commit your changes.
  5. Create a pull request with “Documentation” label.

Top ↑

Create a New Document Create a New Document

To add a new documentation page:

  1. Create a Markdown file in the docs folder.
  2. Add item to the toc.json hierarchy.
  3. Update manifest.json by running npm run docs:build.
  4. Commit manifest.json with other files updated.

Top ↑

It’s likely that at some point you will want to link to other documentation pages. It’s worth emphasizing that all documents can be browsed in different contexts:

  • Block Editor Handbook
  • GitHub website
  • npm website

To create links that work in all contexts, you should use absolute path links without the https://github.com/WordPress/gutenberg prefix. You can reference files using the following patterns:

  • /docs/*.md
  • /packages/*/README.md
  • /packages/components/src/**/README.md

This way they will be properly handled in all three aforementioned contexts.

Top ↑

Code Examples Code Examples

The code example in markdown should be wrapped in three tick marks ``` and can additionally include a language specifier. See this GitHub documentation around fenced code blocks.

A unique feature to the Gutenberg documentation is the codetabs toggle, this allows two versions of code to be shown at once. This is used for showing both ESNext and ES5 code samples. For example, on this block tutorial page.

Here is an example codetabs section:

```js // ESNext code here ```
```js // ES5 code here ```

The preferred format for code examples is ESNext, which should also be the default viewed. The example placed first in source will be shown as the default.

Note: not all code examples are required to include ES5 code. The guidance is to include ES5 code for beginner tutorials, but the majority of code in Gutenberg packages and across the larger React and JavaScript ecosystem is in ESNext.

Top ↑

Editor Config Editor Config

You should configure your editor to use Prettier to auto-format markdown documents. See the Getting Started documentation for complete details.

An example config for using Visual Studio Code and the Prettier extensions:

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

Top ↑

Resources Resources