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 Tuesdays 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.
Documentation types Documentation types
There are two major sets of documentation for the Gutenberg project:
- 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.
- 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.
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. Additionally, see the video walk-through and the accompanying slides for contributing documentation to Gutenberg.
Handbook structure Handbook structure
The handbook is organized into four sections based on the functional types of documents. The Documentation System does a great job explaining the needs and functions of each type, but in short they are:
- Getting started tutorials – full lessons that take learners step by step to complete an objective, for example the create a block tutorial.
- How to guides – short lessons specific to completing a small specific task, for example how to add a button to the block toolbar.
- Reference guides – API documentation, purely functional descriptions,
- Explanations – longer documentation focused on learning, not a specific task.
Templates Templates
A how to guide template is available to provide a common structure to guides. If starting a new how to guide, copy the markdown from the template to get started.
The template is based on examples from The Good Docs Project, see their template repository for additional examples to help you create quality documentation.
Update a document Update a document
To update an existing page:
- Check out the gutenberg repository.
- Create a branch to work, for example
docs/update-contrib-guide. - Make the necessary changes to the existing document.
- Commit your changes.
- Create a pull request using “[Type] Documentation” label.
Create a new document Create a new document
To add a new document requires a working JavaScript development environment to build the documentation, see the JavaScript build setup documentation:
- Create a Markdown file in the docs folder, use lower-case, no spaces, if needed a dash separator, and
.mdextension. - Add content, all documents require one and only H1 tag, using markdown notation.
- Add document entry to the toc.json hierarchy, see existing entries for format.
- Run
npm run docs:buildto updatemanifest.json. - Commit
manifest.jsonwith other files updated.
If you forget to run, npm run docs:build your PR will fail the static analysis check, since the manifest.json file is an uncommitted local change that must be committed.
Using links Using links
It’s likely at some point you’ll want to link to other internal documentation pages. It’s worth emphasizing all documents can be browsed in different contexts:
- Block editor handbook
- GitHub website
- npm website
To create links that work in all contexts, you must 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.
Use the full directory and filename from the Gutenberg repository, not the published path; the Block Editor Handbook creates short URLs—you can see this in the tutorials section. Likewise, the readme.md portion is dropped in the handbook, but should be included in links.
An example, the link to this page is: /docs/contributors/documentation/README.md
Code examples Code examples
The code example in markdown should be wrapped in three tick marks ``` and should 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:
<div class="code-tabs"><button data-language='ESNext' class='code-tab ESNext is-active'>ESNext</button><button data-language='ES5' class='code-tab ES5'>ES5</button><div class='code-tab-block ESNext is-active'>
```js
// ESNext code here
```
</div><div class='code-tab-block ES5'>
```js
// ES5 code here
```</div></div>
The preferred format for code examples is ESNext, this should be the default view. The example placed first in source will be shown as the default.
Note: it is not required to include ES5 code examples. 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.
Callout notices Callout notices
The Block Editor handbook supports the same notice styles as other WordPress handbooks. However, the shortcode implementation is not ideal with the different locations the block editor handbook documentation is published (npm, GitHub).
The recommended way to implement in markdown is to use the raw HTML and callout callout-LEVEL classes. For example:
<div class="callout callout-info">This is an **info** callout.</div>
The following classes are available: info, tip, alert, warning
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
},
Resources Resources
-
Copy Guidelines for writing instructions, documentations, or other contributions to Gutenberg project.
-
Tone and Voice Guide from WordPress Documentation.