Title: Documentation Contributions Published: March 9, 2021 Last modified: October 9, 2026 --- # Documentation Contributions ## In this article * [Discussions](https://developer.wordpress.org/block-editor/contributors/documentation/?output_format=md#discussions) * [Documentation types](https://developer.wordpress.org/block-editor/contributors/documentation/?output_format=md#documentation-types) * [Block editor handbook process](https://developer.wordpress.org/block-editor/contributors/documentation/?output_format=md#block-editor-handbook-process) - [Handbook structure](https://developer.wordpress.org/block-editor/contributors/documentation/?output_format=md#handbook-structure) - [Templates](https://developer.wordpress.org/block-editor/contributors/documentation/?output_format=md#templates) - [Update a document](https://developer.wordpress.org/block-editor/contributors/documentation/?output_format=md#update-a-document) - [Create a new document](https://developer.wordpress.org/block-editor/contributors/documentation/?output_format=md#create-a-new-document) - [Documenting packages](https://developer.wordpress.org/block-editor/contributors/documentation/?output_format=md#documenting-packages) - [Using links](https://developer.wordpress.org/block-editor/contributors/documentation/?output_format=md#using-links) - [Code examples](https://developer.wordpress.org/block-editor/contributors/documentation/?output_format=md#code-examples) - [Callout notices](https://developer.wordpress.org/block-editor/contributors/documentation/?output_format=md#callout-notices) - [Line wrapping](https://developer.wordpress.org/block-editor/contributors/documentation/?output_format=md#line-wrapping) - [Editor config](https://developer.wordpress.org/block-editor/contributors/documentation/?output_format=md#editor-config) - [Images](https://developer.wordpress.org/block-editor/contributors/documentation/?output_format=md#images) - [Video embeds](https://developer.wordpress.org/block-editor/contributors/documentation/?output_format=md#video-embeds) * [Resources](https://developer.wordpress.org/block-editor/contributors/documentation/?output_format=md#resources) [ Back to top](https://developer.wordpress.org/block-editor/contributors/documentation/?output_format=md#wp--skip-link--target) A guide on how to get started contributing documentation to the Gutenberg project. ## 󠀁[Discussions](https://developer.wordpress.org/block-editor/contributors/documentation/?output_format=md#discussions)󠁿 The [Make WordPress Docs blog](https://make.wordpress.org/docs/) 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](https://make.wordpress.org/chat)( 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](https://github.com/WordPress/gutenberg). To find documentation issues to work on, browse [issues with documentation label](https://github.com/WordPress/gutenberg/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3A%22%5BType%5D+Documentation%22+). ## 󠀁[Documentation types](https://developer.wordpress.org/block-editor/contributors/documentation/?output_format=md#documentation-types)󠁿 There are two major sets of documentation for the Gutenberg project: 1. [User documentation](https://wordpress.org/documentation/article/wordpress-block-editor/) 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](https://developer.wordpress.org/block-editor/) 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](https://developer.wordpress.org/block-editor/contributors/documentation/?output_format=md#block-editor-handbook-process)󠁿 The block editor handbook is a mix of markdown files in the `/docs/` directory of the [Gutenberg project repository](https://github.com/WordPress/gutenberg/) and generated documentation from the packages. An automated job publishes the docs every 15 minutes to the [block editor handbook site](https://developer.wordpress.org/block-editor/). See [the Git Workflow](https://developer.wordpress.org/block-editor/contributors/code/git-workflow/) documentation for how to use git to deploy changes using pull requests. Additionally, see the [video walk-through](https://wordpress.tv/2020/09/02/marcus-kazmierczak-contribute-developer-documentation-to-gutenberg/) and the accompanying [slides for contributing documentation to Gutenberg](https://mkaz.blog/wordpress/contribute-developer-documentation-to-gutenberg/). ### 󠀁[Handbook structure](https://developer.wordpress.org/block-editor/contributors/documentation/?output_format=md#handbook-structure)󠁿 The handbook is organized into four sections based on the functional types of documents. [The Documentation System](https://documentation.divio.com/) 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](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-create-block/). * **How-to guides** – short lessons specific to completing a small specific task, for example [how to add a button to the block toolbar](https://developer.wordpress.org/block-editor/how-to-guides/format-api/). * **Reference guides** – API documentation, purely functional descriptions, * **Explanations** – longer documentation focused on learning, not a specific task. ### 󠀁[Templates](https://developer.wordpress.org/block-editor/contributors/documentation/?output_format=md#templates)󠁿 A [how-to guide template](https://raw.githubusercontent.com/WordPress/gutenberg/trunk/docs/contributors/documentation/how-to-guide-template.md) 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](https://github.com/thegooddocsproject/templates) for additional examples to help you create quality documentation. ### 󠀁[Update a document](https://developer.wordpress.org/block-editor/contributors/documentation/?output_format=md#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 using the [[Type] Developer Documentation](https://github.com/WordPress/gutenberg/labels/%5BType%5D%20Developer%20Documentation) label. ### 󠀁[Create a new document](https://developer.wordpress.org/block-editor/contributors/documentation/?output_format=md#create-a-new-document)󠁿 To add a new document requires a working JavaScript development environment to build the documentation, see the [Working with JavaScript for the Block Editor](https://developer.wordpress.org/block-editor/getting-started/fundamentals/javascript-in-the-block-editor/) guide: 1. Create a Markdown file in the [docs](https://github.com/WordPress/gutenberg/tree/HEAD/docs) folder, use lower-case, no spaces, if needed a dash separator, and `.md` extension. 2. Add content using markdown notation. All documents require one and only `h1` tag. 3. Add document entry to the [toc.json](https://github.com/WordPress/gutenberg/blob/HEAD/docs/toc.json) hierarchy. See existing entries for format. 4. Run `npm run docs:build` to update `manifest.json`. 5. Commit `manifest.json` with 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. ### 󠀁[Documenting packages](https://developer.wordpress.org/block-editor/contributors/documentation/?output_format=md#documenting-packages)󠁿 Package documentation is generated automatically by the documentation tool by pulling the contents of the README.md file located in the root of the package. Sometimes, however, it is preferable to split the contents of the README into smaller, easier- to-read portions. This can be accomplished by creating a `docs` directory in the package and adding` toc.json` file that contains references other markdown files also contained in the` docs` directory. The `toc.json` file should contain an array of pages to be added as sub-pages of the main README file. The formatting follows the [`manifest.json`](https://github.com/WordPress/gutenberg/blob/HEAD/docs/manifest.json) file that is generated automatically. In order for these pages to be nested under the main package name, be sure to set the `parent` property correctly. See the example below that adds child pages to the [`@wordpress/create-block` section](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/). ```language-json [ { "title": "@wordpress/create-block External Template", "slug": "packages-create-block-external-template", "markdown_source": "../packages/create-block/docs/external-template.md", "parent": "packages-create-block" } ] ``` ### 󠀁[Using links](https://developer.wordpress.org/block-editor/contributors/documentation/?output_format=md#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 the links. An example, the link to this page is: `/docs/contributors/documentation/README.md` **Note:** The usual link transformation is not applied to links in callouts. See below. ### 󠀁[Code examples](https://developer.wordpress.org/block-editor/contributors/documentation/?output_format=md#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](https://help.github.com/en/github/writing-on-github/creating-and-highlighting-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 `JSX` and` Plain` code samples. Here is an example `codetabs` section: ```language-md \{\% codetabs \%\} \{\% JSX \%\} ```js // JSX code here ``` \{\% Plain \%\} ```js // Plain code here ``` \{\% end \%\} ``` The preferred format for code examples is JSX. 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 plain JavaScript code examples for every guide. The recommendation is to include plain code for beginner tutorials or short examples, but the majority of code in Gutenberg packages and across the larger React and JavaScript ecosystem are in JSX that requires a build process. ### 󠀁[Callout notices](https://developer.wordpress.org/block-editor/contributors/documentation/?output_format=md#callout-notices)󠁿 The Block Editor handbook supports the same [notice styles as other WordPress handbooks](https://make.wordpress.org/docs/handbook/documentation-team-handbook/handbooks-style-and-formatting-guide/#formatting). 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: ```html
This is an **info** callout.
``` The following classes are available: `info`, `tip`, `alert`, `warning` ```html
This is a **tip** callout.
This is an **info** callout.
This is an **alert** callout.
This is a **warning** callout.
``` Note: In callout notices, links also need to be HTML `` notations. The usual link transformation is not applied to links in callouts. For instance, to reach the Getting started > Create Block page, the URL in GitHub is https://github. com/WordPress/gutenberg/blob/trunk/docs/getting-started/devenv/get-started-with- create-block.md/ and will have to be hardcoded for the endpoint in the Block Editor Handbook as `https://developer.wordpress.org/block-editor/getting-started/create- block/` to link correctly in the handbook. ### 󠀁[Line wrapping](https://developer.wordpress.org/block-editor/contributors/documentation/?output_format=md#line-wrapping)󠁿 Do not hard-wrap prose. Keep each paragraph, list item, and table row on a single line and let your editor soft-wrap it on screen. There is no line length limit for documentation; the `MD013` rule is disabled in the project’s markdownlint configuration. Hard-wrapped text renders the same, but it makes later edits hard to review: changing one word reflows the paragraph and the diff then covers every line of it instead of the line that actually changed. Hard wrapping is also an accessibility problem in the source file. A screen reader reads a plain text file line by line and a braille display shows it one line at a time, so a sentence broken across four lines arrives as four fragments, and most screen readers cannot navigate source text by sentence to piece it back together. A sentence kept on one line means reading a line gives a complete thought. The Google developer documentation style guide gives the same rule: [“Don’t force line breaks (hard returns) within sentences and paragraphs.”](https://developers.google.com/style/accessibility) Keep line breaks where Markdown needs them, such as between list items and table rows, and never reflow fenced code blocks. ### 󠀁[Editor config](https://developer.wordpress.org/block-editor/contributors/documentation/?output_format=md#editor-config)󠁿 You should configure your editor to use Prettier to auto-format markdown documents. See the [Getting Started documentation](https://developer.wordpress.org/block-editor/contributors/code/getting-started-with-code-contribution/) for complete details. An example config for using Visual Studio Code and the Prettier extensions: ```language-json "[[markdown]]": { "editor.defaultFormatter": "esbenp.prettier-vscode", "editor.formatOnSave": true }, ``` Depending on where you are viewing this document, the brackets may show as double. The proper format is just a single bracket. ### 󠀁[Images](https://developer.wordpress.org/block-editor/contributors/documentation/?output_format=md#images)󠁿 Images displayed in the Block Editor Handbook must be hosted in the [developer.wordpress.org](https://developer.wordpress.org/) Media Library, not linked from GitHub. Images linked directly from GitHub (for example, URLs starting with `https://raw. githubusercontent.com`) are subject to rate limiting and can fail to load once the documentation is synced to the Block Editor Handbook. Hosting them in the Media Library avoids this. To add an image: 1. Upload the image to the Media Library on developer.wordpress.org. This requires additional permissions—if you don’t have access, ask in the `#docs` channel in [Make WordPress Slack](https://make.wordpress.org/chat) for assistance. 2. Copy the URL of the uploaded image. It should look something like `https://developer. wordpress.org/files/2026/06/your-image.png`. 3. Reference the image in markdown using that URL, with descriptive alt text. For example: ```language-md ![Descriptive alt text](https://developer.wordpress.org/files/2026/06/your-image.png) ``` The Media Library does not accept SVG uploads. If an SVG is **displayed** in the handbook, upload a raster version (such as a PNG) to the Media Library and reference that. Only keep an SVG in the repository and link to it directly when it is meant to be **downloaded** (for example, a logo offered as a vector file)—a download link isn’t fetched on every page render, so it isn’t affected by the rate limiting. ### 󠀁[Video embeds](https://developer.wordpress.org/block-editor/contributors/documentation/?output_format=md#video-embeds)󠁿 Videos in the Block Editor Handbook need to be hosted on the [WordPress YouTube channel](https://www.youtube.com/@WordPress) as unlisted videos. This process requires additional permissions. Reach out in the# marketing Slack channel for assistance. Once the video has been uploaded to YouTube, retrieve the video embed link. It should look something like this: ``` https://www.youtube.com/embed/nrut8SfXA44?si=YxvmHmAoYx-BDCog ``` Then, place the following code where you want the video to be embedded in the documentation. Update the embed link and video title accordingly. ```html ``` Videos should have an aspect ratio of `16:9` and be filmed at the highest resolution possible. ## 󠀁[Resources](https://developer.wordpress.org/block-editor/contributors/documentation/?output_format=md#resources)󠁿 * [Copy Guidelines](https://developer.wordpress.org/block-editor/contributors/documentation/copy-guide/) for writing instructions, documentation, or other contributions to the Gutenberg project. * [Tone and Voice Guide](https://make.wordpress.org/docs/handbook/documentation-team-handbook/tone-and-voice-guide/) from WordPress Documentation. First published March 9, 2021 Last updated October 9, 2026 Edit article [ Improve it on GitHub: Documentation Contributions ](https://github.com/WordPress/gutenberg/edit/trunk/docs/contributors/documentation/README.md) [ Previous: Blocks are the Interface](https://developer.wordpress.org/block-editor/contributors/design/the-block/) [ Next: Copy Guidelines](https://developer.wordpress.org/block-editor/contributors/documentation/copy-guide/)