Repository navigation
Add READMEs to all block-editor components #22891
Description
The Block Editor package in Gutenberg is full of components used to build blocks or block editors. These components lack documentation.
This issue is a tracking issue for the documentation effort to add READMEs to all these components.
If you want to help with this:
- Grab a component in the block-editor package that lacks a README
- Comment on the issue that you want to help document this component
- Write a README.md file for this component following the same format as the already documented components.
Updated by @t-hamano
If someone works on this issue, in addition to adding a README file, it would be great if we could also add JSDoc.
The block editor package reference is generated with a JSDoc reference for each component. Components that don't have JSDoc will look like this in the reference:
The recommended complete JSDoc format should look like this:
/**
* Component description here.
*
* @see https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/my-component/README.md
*
* @example
* ```jsx
* function MyComponent() {
* return (
* <MyComponent />
* );
* }
* ```
*
* @param {Object} props Component props.
* @param {string} props.prop1 props description here.
* @param {Array} props.prop2 props description here.
* @return {Element} My component control.
*/
export default function MyComponent( {
prop1,
prop2,
} ) {
return (
<div>
My Component
</div>
);
}
Activity
alita-moore commentedon Jun 13, 2020
I want to make a README for the block-alignment-matrix-toolbar, issue #22516 ; How should I proceed? Is this a README for the issue or for the component?
youknowriad commentedon Jun 15, 2020
@alita-moore yes, a README is needed for that component. so you should add a file to the component folder name it README.md, copy some existing component README to get the "base template" and fill it.
alita-moore commentedon Jun 15, 2020
Okay,
This README
Doesn't have a very defined structure. Are you saying to copy the format in terms of linking to the parent directory?
youknowriad commentedon Jun 15, 2020
Yes, this is not the best example. This might work better https://github.com/WordPress/gutenberg/blob/master/packages/components/src/button/README.md
alita-moore commentedon Jun 15, 2020
Oh okay, that's much better.
Thank you for info, I'll get cracking 👩💻
JustinyAhin commentedon Aug 26, 2020
Working on a pull for BlockBreadcrumb componenent https://github.com/WordPress/gutenberg/tree/master/packages/block-editor/src/components/block-breadcrumb
JustinyAhin commentedon Aug 26, 2020
I've identified all the packages that haven't yet a README.
JustinyAhin commentedon Aug 26, 2020
Block Editor: Warning: Add README.md
Block Editor: Warning: Add README.md (#25574)
dgwyer commentedon Oct 21, 2022
carolinan commentedon Mar 2, 2023
Do we only document items that are exported? (part of this list https://github.com/WordPress/gutenberg/blob/trunk/packages/block-editor/src/components/index.js)
I would like to help but it has been difficult for me to figure out which of these are actionable.
1 remaining item
juanmaguitar commentedon Jun 28, 2023
For reference, The
README.mdat https://github.com/WordPress/gutenberg/blob/trunk/packages/block-editor/src/components/alignment-control/README.md is a good model to follow for the rest of the componentstalldan commentedon Jun 29, 2023
Just thought I'd mention that I have a few months of leave coming up, so won't be able to work on these for a while. I notice I was assigned a few.
mburridge commentedon Jun 29, 2023
Hi @talldan, please feel free to re-assign those to someone else that you deem has the technical knowledge required to create the readme. Thanks.
t-hamano commentedon Dec 14, 2024
If someone works on this issue, in addition to adding a README file, it would be great if we could also add JSDoc.
The block editor package reference is generated with a JSDoc reference for each component. Components that don't have JSDoc will look like this in the reference:
The recommended complete JSDoc format should look like this:
0x8sksr commentedon Jan 6, 2025
Can guide me on how to start or just go with the example from the other documented components, such as this one for button? Thanks!
t-hamano commentedon Jan 7, 2025
@0x8sksr There are many components in the
block-editordirectory that already have READMEs, so you can use those as a reference.stokesman commentedon Jan 28, 2025
For components that are used in Block Supports would it be a good idea include a suggestion for that API? For example,
SpacingSizesControlcould point out that Spacing support may facilitate their use case. The only concern I can think of might be if the block supports switches to a different control it would make the suggestion incorrect so including such suggestions is more maintenance burden.stokesman commentedon Jan 28, 2025
A issue with the guidance to follow the format of existing READMEs is that not all aren’t consistent. The biggest difference I find is that some include "Development guidelines" as a heading above "Usage" and "Props". I thought the point should be raised to settle on a more specific guidance. My feeling is the "Development guidelines" heading should be avoided in the future. If so, we could also remove that from existing READMEs that have it. I didn’t see way to get a URL for the exact search but here’s the query that can be pasted in to search:
carolinan commentedon Mar 6, 2025
Hi
A suggestion to put this issue on hold was brought up in the WordPress Slack channel (account needed).
Currently there are 149 developer documentation pull requests open that are awaiting review, from 2021 and later.
https://github.com/WordPress/gutenberg/pulls?q=is%3Apr+is%3Aopen+label%3A%22%5BType%5D+Developer+Documentation%22+review%3Anone
Before opening new pull requests for this issue please consider reviewing one of the existing pull requests.
Another idea is to arrange regular scrubs where these pull requests are reviewed, so that they do not continue to become stale/ out of date.
youknowriad commentedon Dec 5, 2025
I'm going to close this issue. I don't feel like it adds too much value.