Recently, a detailed Core Blocks reference section was proposed for the Handbook — providing structured API An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. documentation for every block Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. shipped in Gutenberg. The approach was to auto-generate these pages directly from each block’s block.json file, the single source of truth for a block’s attributes, supports, and metadata.
Understanding how a core block works today means reading its source code directly. A block is defined by attributes, supports, context, selectors, and parent/child relationships — but none of these are documented in context for any individual block. To learn about a specific block, a developer has to read its block.json JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. file — which shows the values but does not explain what they mean — and then separately hunt through the general documentation to understand each property. Per-block documentation with contextual links to each concept would close that gap entirely.
The same problem affects LLMs: without documented context for each property, they have to parse source files to infer semantics, spending more tokens and filling context unnecessarily. This is important for AI-assisted creation of templates, template parts, patterns, and other block editor content.
Most of this detail already exists in the codebase. If it can be surfaced automatically, there’s no good reason to leave it buried.
A key part of the proposal is that documentation is generated into a README.md file inside each block’s source directory — for example, packages/block-library/src/paragraph/README.md.
This follows the same convention already established for component documentation, where gen-components-docs generates a README.md inside each component’s directory at packages/components/src/{component}/README.md.
Video transcript (click to expand)
Birgit Pauli-Haack:
All right, so welcome everybody and those who come in today. And for those are watching the recording, this is a hallway hangout for the proposal Juan Ma posted on the make blog (versus network, site) on Auto Generate Block Editor handbook documentation from the block JSON. And the proposal is very detailed on things. What we’re going to do today is that Juan Ma is going to talk us through a little bit about the goals and about the reasons how it’s implemented. And then he also has his local development set up so he can demo things, how it’s going to be, how it’s going to be displayed, published on the developer.WordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ block editor handbook and also how it’s going to show up on the GitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged by the repository owner. https://github.com/ repo. And then. Well, I’m sure Juan Ma will be open for questions and we can also discuss next steps or how the documentation team can, can come in and make updates, or how contributors globally, contributors to code or contributors to the documentation team can augment some of the documentation that’s going to be automatically created. But there are some manual places where you can fit in some additional explanations. All right, I think you’re up now. Thank you for coming. Yeah. And taking the time.
JuanMa Garrido:
Yeah, thank you so much, Birgit, for facilitating this meeting and helping unblocking this, this whole change and thank you Andrea, for, for attending. Yeah. So this proposal is to. The goal of, of this proposal is to make the life easier for developers to understand blocks, to understand how they are built, how they are supposed to be used, and to surface a lot of information that was kind of hidden in the code, but displaying that in a more friendly way for developers and for the final users. Because what we have now is this. What we have now is a very brief list of the properties that define each block and a quick. And a link to the source code. So this is what we have right now. So there’s no context about what supports mean, there’s no context about what attributes mean, there’s no context about what, what does it mean allowed blogs and that makes it hard for people. They need to really do their own research. So I’m thinking from the perspective of a first time user that arrives to this place, they don’t know anything about blocks and they find this and that’s really hard to grasp, to understand. And I think we can do better in that sense. Also as a reference for developers. This is also not super useful. I mean you can get the list of supports here, but for example, you don’t have an explanation of what’s the meaning of each report and that’s something that could be improved. There’s no example of how the markup is supposed to work for each blog. So I think there could be a better way to show this information. And I would like to highlight that this is not only important for developers, but also for artificial intelligence. Because in this era I think AI models are the first users of the and I think having better a more detailed information for each block available in the repository, but also the documentation is going to be very helpful for models to then recommend a specific developments using blockchain block markup, for example, I’m thinking about patterns or templates or any other thing that would mean, I don’t know, less tokens and less hallucinations from the model. So for all those reasons there was a conversation that we had like with Birgi, then with Jonathan and Justin and Ryan within the team and with we discussed about this and Jonathan started a first attempt of doing this and then I continued the work and what I got was this. So this is what we have right now in production and I’m going to show how this would look like in production if this pull request is merged. So we would get something like this. This is the same page done before, but now we have now a section for each block category The 'category' taxonomy lets you group posts / content together that share a common bond. Categories are pre-defined and broad ranging.. So my approach with this was okay, let’s keep the current page because I like having in one page all the blocks, but let’s expand this with more pages and with more detailed information about each block. So we have here all the blocks, but then the thing is that we have now links to both the category that the block belongs to and the detailed information. So let’s take the first one, Core accordion. If we go to this page we can see that this is below design blocks. But we have also a page for each block category, Media blocks, reusable blocks, text blocks. So we have like these two ways of. See the list of blocks available in Core. But if we go for example to the details block, we can see the detailed page for the details block. And which information do we have here? All this information is in the code. But now we have surfaced this. So we have the internal name for the block, the category and this is a link to the category this block belongs to. So we can see it’s siblings, so to speak. We have the version and here we have information about the versions. So we are starting adding more context about each piece of information. Then we have the block type and we get linked to a page where this thing is explained. Because blocks can be like Purely static, purely dynamic, or they can mix both approaches. So here based on the existence of specific files, it kind of categorized them between static, dynamic or hybrid. I think this is good information to have then internal keywords for the block and then the attributes. So we get this from the blood JSON, but we get more context because we can actually link to the parts of the documentation where each one of these things are explained. For example, the type of an attribute is we have here the value, but we can get a link to what does it mean and what are the possible values an attribute can have for this, the default value. And we get here a link to the part of the documentation, the attributes page where this is explained the rest for source role Regarding supports, I think this is really cool because it not only detail, it not only details the list of supported properties, but also we get a link to the the explanation of each one of these supports, which I think is really cool. And as you can see, all this information provides a better experience for someone approaching to the blog or even for an experienced developer because it really saves a lot of time. If I want to understand quickly what is something, then we have an example of the markup of each block. And I think this is really cool because this information is is taken for the fixtures that are used to test the block. So this information is used internally to verify that the block behaves or that the, the. The block does what it’s supposed to do. And, and there are a lot of, they are called fixtures in testing terms. But this information is a good reference for anyone that wants to use this this block. So we can also surface this surface that automatically. And then finally we get a link to the, to the, to the source of this information. We get a link to the blog JSON for each block. And also here we have a reference of the explanation of the block JSON. So we are again adding more context to that. And then finally we get a link to the, to the whole directory with all the files that define each block. And all this process is generated automatically using a script.
Andrea Roenning:
So
JuanMa Garrido:
I don’t know if there are any questions about this before I enter into the explanation of the technical aspects of the this change.
Birgit Pauli-Haack:
Andrea, everything is clear.
Andrea Roenning:
Yes, I have some specific questions, but they can wait.
JuanMa Garrido:
Okay.
Birgit Pauli-Haack:
Okay,
JuanMa Garrido:
so what I can do is I can explain how this works internally, how these pages are generated, when will they be generated and yeah, some aspects of the implementation. So the pull request is this one?
Birgit Pauli-Haack:
Yeah, I shared it in the chat window just in case.
JuanMa Garrido:
So first of all, this Pull request will add a lot of markdowns because it’s the first time that is generated, it will add a REDMI MD for each one of the blocks. This is a one time thing because after that all those redmis will be updated only when there are changes to that affect these Redmi MDs. Second thing that I think is important is that this pull request provides a way to that two type of information coexist, like manual information and automatically generated information. So for each block. And we can see an example here in the navigation block which is here. And we can go to View file and I can show the row.
Birgit Pauli-Haack:
So that’s a little small.
JuanMa Garrido:
Yes. Yes. Let me.
Birgit Pauli-Haack:
You need to squint a bit. Yeah. So very good.
JuanMa Garrido:
Yeah. Is it fine now?
Birgit Pauli-Haack:
Yeah.
JuanMa Garrido:
Okay. So the navigation block, it had some previous information. In fact, I think it was the only REDMI MD that was created for a block. Only a few of them, this one and some other one that it has some information that was manually added. So this change will only generate automatic content between these tokens. Everything that is between these tokens will be automatically generated. So as long as we don’t touch these tokens, we can add any manual information outside. And there’s a message here clarifying that this follows the same approach that is being used for the REDMI mds for the packages. Because the packages I can go, maybe I can quickly go and check the REDMI MD for. If we go to packages, each package it has this part, the API. If we go edit redmi. Yeah, as you can see, there’s also information that is manually added. But then we have a start token. All this part is automatically generated. So it’s using the same, the same idea, the same approach. We can have manual and automatic content coexisting in the same REDMI md. Another technical detail that I think is relevant is to explain how we can trigger the generation of this content. And this is managed by a new script that has been add it here is called Docs Block Detail. This is part of package JSON and it has been added to the family of DOCS scripts. There are a lot of Docs script. For example, there is Docs API Ref is the script that generates the API content for each package, like as we saw a minute ago. So now there’s a new script called Docs Block Detail that generates the readme if it doesn’t exist or it updates the readme for the affected changes. Another. Let me see if I can show this. Another interesting thing is that it has been added this Script this. To the lint state. So if I not run. In the same way that we have API ref and the block details will be launched for each. For each. So every time there is a change in a block JSON, it will. It will trigger these scripts in the same way that we are calling the other ones. Okay, what else? And basically I have tried to. Make this implementation as close as other things that are already happening. So the same things we do for other parts of the documentation now we are also doing that for blocks. For example, there is a automatic process for components. There is an automatic process for the REDMI MD of each package. And now we have another one for blocks. For blocks detail this docs blocks is the automatic process that generates the current page we have. This is the current page we have. And this is triggered by this process. Now we have another process that updates this page and also updates or generates the other Redmi MDs for each block and the categories pages. And what else can I say about this? I think I have covered like what was on my mind that I think could be relevant. So yeah, I’m going to stop talking now and answer to listen to any questions.
Andrea Roenning:
One question I have is, is it going to be clear if changes in the Gutenberg repository versus the core update?
JuanMa Garrido:
That’s a very good question. I haven’t included the change in this pull request. So we could do this in two ways. I could expand this pull request and make it bigger and try to other information. The thing is that that information is not available for any API in the Gutenberg repo. So maybe my. My feeling is that I agree that this should be added to this information, but maybe this pull request is not the place to add that. So in fact I was mentioning this to bitgit earlier. I have opened this issue to actually surface that information to this issue I opened was most referred to the API of each package because each function there is no clear information about which Gutenberg version it belongs to or if it’s available in Core or not. And I agree that this is essential information to have. But this is using some internal processes because I have opened the issue, but I have already some work in progress for this. So I think the same internal processes could be applied to the blocks as well. So yeah, maybe and that would be my. My approach is that adding the Gutenberg version where each block was included or if it’s available in WordPress Core or not, maybe that should be added as a. In a pull request after this is merged.
Birgit Pauli-Haack:
That makes sense to me. Yeah, yeah. I Agree too because I think it’s important to have the processes to get all the documentation in the document on the handbook first and then wiggle it down to what are the other details that we need and do we need to have it for a process on the repo and then make it for, for every function, for every block, for every. Yeah. Detail that is in the block editor. And that’s a, it’s a much bigger conversation because the developers need to be kind of, it needs to be clear which, which version that is. And, and that’s. I, I think one of the biggest Gutenberg plug repo problems is we have three different, well, even four. No, we have WordPress core, we have Gutenberg and we have the Gutenberg experiments. And then. So it’s a three version process. And yeah, it’s going to be really interesting to see how to implement that, but I don’t want to. I definitely, personally, I don’t think we should delay this process because it’s such fundamental change and so much more helpful than this other detail here. What other questions do you have, Andrea?
Andrea Roenning:
One other question I have is, is it possible to have blocks grouped in more than one category?
JuanMa Garrido:
Is it possible to do that from a block JSON?
Andrea Roenning:
Yeah, I think. Well, I think it is, but I think the reason why it would be nice is it would be good to have a deprecated category because I think we have like a handful of deprecated blocks and it would be nice to kind of see them at a GL. But that could be a future Mr. As well. I don’t know if that makes sense in this scope of work.
JuanMa Garrido:
Well, that information is, I think is included. Let me see.
Birgit Pauli-Haack:
I’ve seen it.
JuanMa Garrido:
So what was added was a call out at the beginning of each block? No, I don’t think so. What was added was a call out with the experimental blocks. But I don’t think because deprecated blocks. Yeah, they also exist in the repository. But yeah, I haven’t thought of that. That could be something interesting to add in this pull request. Yeah, you’re right.
Andrea Roenning:
I’ll add a note to the PR just so that it’s documented there or
JuanMa Garrido:
maybe later not sure if a category is the best place because there is an idea of category and I think it could be, could be confusing for people to add a category that is not really a category.
Andrea Roenning:
Yeah, but it could be something else, some other attributes.
JuanMa Garrido:
But for example here, that could be a specific section. Yeah, I don’t know.
Birgit Pauli-Haack:
Yeah, I did a similar kind of dive into After I saw what you did, who am I? I did a similar thing to just have a, a call out on the Gutenberg Knightley on what are the experiments blocks in the experiments. And I saw the deprecated part and I had the code discarded and that was relatively easy to do, to not display. So there is already a, A, a place where that is communicated. So yeah, that can certainly be part of the page. Yeah. Even if so they don’t, I, I, I understand that you say, okay, I want it in a category because I have a list of all of it. Yeah. But it could be probably even a deprecated page separately, but have it in a separate pr. Yeah, I can see that.
JuanMa Garrido:
Yeah. The advantage of having all blocks here is that we could look for specific terms. So if we add deprecated here, you can access to all the deprecated blocks. So that could be a first and maybe that’s enough. But a second thing that could be done here is to maybe group them in a specific section and maybe adding a notice here highlighting that there are some deprecated blocks. Click here to see all of them and that could link to maybe a section that is at the end of the, of this doc listing all the deprecated blocks. Yeah, something. That is useful, but maybe that doesn’t add more noise to the whole block directory.
Birgit Pauli-Haack:
Yeah, I like it. Yeah.
Andrea Roenning:
And at a minimum, even just adding a bullet there that some blocks are deprecated, maybe that would be a good first step.
JuanMa Garrido:
I think that information could be automatically generated. So maybe we could add directly here like a call out saying please take into account that the following blocks are deprecated, blah, blah, blah and blah, and we can link to the blocks or something. That could be done.
Birgit Pauli-Haack:
Good. Andrea, do you have any more questions?
Andrea Roenning:
No, I’ll just share. So I’m a contributor for the Help Hub user. Facing Docs team and keeping up with changes between WordPress core versions is a challenge. A lot of times there are attributes coming in and it’s hard to know which blocks are getting them. So this will be helpful even just to be able to have a place to easily look at it without digging through block JSON. But yeah, down the road, if there was a change log or some way where we can see fit text is stored differently than it was before that, that kind of thing, I, I’m it, that would be lovely, but I don’t think that needs to be part of this. Mr. A changelog would be great.
Birgit Pauli-Haack:
Yeah. Yeah. It’s really hard for the user documentation to make Anything automatic. Yeah, because it has all the different screens that you need for that. What is in the block settings? What’s it’s in. How does a block look like? I don’t envy you. I did this probably for a year and a half back in 2020 to kind of try to figure out how to do end user documentation. So, yeah, I think with Play, I don’t know, are you experimenting with Playground on that?
Andrea Roenning:
I use Playground to take, you know, videos of the blocks in action. For example, we’ve got Nikon and Breadcrumb blocks coming in. And then I read through the prs and I look through the block. Yeah, so it’s. But yeah, it’s. And the source of truth is hugely helpful. I appreciate that.
Birgit Pauli-Haack:
So thank you. Yeah, yeah, yeah.
Andrea Roenning:
Keeping track of all of the incoming changes for Core is challenging, but I think this would be very helpful and it would also be helpful to get other developers involved. If they see a change on the readme, they can open a pull request and make an update, I think.
Birgit Pauli-Haack:
Yeah, yeah, yeah. That brings me to my question that I have for one. So if I see something that’s not correct, what would be my step after?
JuanMa Garrido:
Something that is something that is not correct in the content or in the implementation?
Birgit Pauli-Haack:
No, in the. Think about it. Okay, you have it all merged and now it’s on auto processing. But I’m now a developer and try to figure out what do I do with this block or I want to style it. Now I find it difficult to get to that information and think I need to add something to that styling for that block, like accordion block or a tabs block or something like that. Yeah. So what would I do?
JuanMa Garrido:
Yeah, well, all the tools that are used internally in Gutenberg to generate content automatically for docs, they are all in two places. One of them is Tools API docs, and this is where the specific tool for the blocks will live if we go to the pull request. So talking about fine tuning the output, for example, of the. The blocks that would belong to. Yeah, this is too big for this. That would belong to this script. This is where all the. All the magic happens, so to speak. This is where this is all was created with the help of cloud code. So, yeah, maybe if there’s. I think this is enough, but maybe we could simplify the way to, I don’t know, create a template that can be modified without affecting the process. But from a developer perspective, if I want to fine tune the output for each page, this is. The file should be updated.
Birgit Pauli-Haack:
Okay. So if I don’t want to update all the pages. I only want to have a certain block documentation. I go to the package block library and then to the readme of that block.
JuanMa Garrido:
Yes. If I want to add manual information to a specific block, what can we do is go to. Because all the. So what this pull request is going to do is going to add a REDMI MD to each one of the blocks that are available in the block library package. The block library package contains all the core blocks. So in terms of code, if we go to Gutenberg packages block library now necessary, we have all the blocks. But right now no block has a REDMI md. So this pull request will add a REDMI MD inside the folder of each block, which makes a lot of sense because it’s kind of a description of what’s going on here. So what we can do is to add the manual information for that block with a pull request using the process we use for other changes in the repository. And any information that is outside of these tokens will be respected, will not be modified by any process. So, for example, if we want to add custom information for the accordion heading, we can just add here whatever information we want or even after the token and that will be respected in the automatic process. It won’t be removed.
Birgit Pauli-Haack:
Super. And it would follow normal markdown formation format. And then somebody needs to review it and then it will be merged. And then after the merge, within a day or within an hour, I think the block editor handbook will be updated. Right. Good.
JuanMa Garrido:
I think every 15 minutes or something like that. Right.
Birgit Pauli-Haack:
That’s pretty fast for someone who’s a new contributor and just wants to update the documentation and kind of see, oh, this is not clear. Let’s do some manual, some additional explanation, then that can be done. That’s wonderful. Excellent. Yeah. Because right now it’s a really, really more difficult to do that. Yeah, you raised your hand, Andrea.
Andrea Roenning:
Yeah, I was going to propose that, you know, maybe towards the bottom, if we were going to list out accessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility) issues or, you know, maybe link to open accessibility tickets, that would be a lovely place to do it. So they’re not like the very first thing you see, but if. Right. It’s nice that we’ve got kind of the ice cream sandwich where we’ve got manual data and then generated data and then we can still add manual data at the bottom, if that makes sense.
Birgit Pauli-Haack:
Totally. Yeah. Yeah. Especially because accessibility issues was one of the comments on the proposal by Joe Dawson. And I think it definitely needs somebody from the accessibility team to kind of add some information to each blocks readme and then it can be automatically added to the developer handbook.
JuanMa Garrido:
Yeah, Jodo suggested that. And yeah, the way to add this information, there is no way to get that information automatically as of today. But now we will have a place to add that information in the redmi and manually. So it’s available.
Birgit Pauli-Haack:
It’s very good. Yeah. No, I like that. Hybrid. Yeah. Automate what’s possible. Yeah. And then manage manually what is different or what needs additional. Additional explanation because it’s outside of the ordinary. Yeah. So I think, Andrea, are you any closer to understanding this process or are you. Do you have any more questions?
Andrea Roenning:
No more questions on my end. This is really exciting. I think it would be very helpful.
Birgit Pauli-Haack:
Yeah, I think so too. Yeah. All right. Joan, Mo, anything you want to add?
JuanMa Garrido:
Well, I would like to kind of share my impression about where we are now and what would be the next steps. So from the moment this new pull request, because the history of this pull request is that it was open, it was reviewed by different developers, like three or four developers. It was merged, but then it was reverted because there were concerns that this was. This wasn’t discussed enough and there wasn’t a good consensus about that. So after that this pull request was opened and there was a more formal process to gather feedback and we published the post and make a WordPress core. Now we’re having this Halloway hangout. The feedback timeline ends next Monday, so there’s still time to provide feedback. But I would like to summarize the state of the pull request right now. I think that the consensus for the Docs team, I would consider it given. I mean, I would consider that the Docs team has supported this feature as per the comments in the proposal and the comments in the Slack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/ channel. So that’s like a new thing that we didn’t have before. And also the specific technical aspects because there were a lot of suggestions to improve the code that all those things were addressed in the previous pull request. But in this pull request there are new things. Most of them have been addressed. There are only a few ones that I didn’t address until I knew for sure that we were going to move forward with this task. But one big one was this about that George asked if, because yeah, this pull request is going to add a lot of new ReadMe files in the repository. That means a lot of new lines. So that’s a really valid concern. But even with that, I think this is still the best way to tackle this theme because that information will live in the repository. Which I think is where it should live. And then the documentation is just like a nicer way to to provide that information. And also I think it’s important that that information is available from both repository and from the documentation so there are no gaps. So if you access to the info from the repo or from the documentation site, the info is already there. And Dion from the meta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. team also thinks that this is the way to go. So in that sense I think the major concerns are now addressed and there are clear responses to all those things. But as I said, there’s still time to ask questions to raise more concerns and to provide more feedback. But I think we are in a better place now to move forward with this.
Birgit Pauli-Haack:
Yeah, so you heard it. If you’re listening to this before May 25, you still get a chance to have put in your feedback. Your Yes, I love this. Or well if you do this, there are some concerns. Yeah. Either way, leave it on the make blog post or on the pull request. That’s definitely the two places to to leave that. Feed your feedback there and we close this horror hangout now. Thank you both Andrea and Juan Ma for being here and have a discussion on this. And Fuanli, I’m really excited about it because I couldn’t really make a visual thing so I asked Juan Ma if he would demo some of the things. So I’m really happy that we did this. I will post the link to the video on the proposal and also in the channel doc’s channel as well as the co editor channel once it’s ready. And I’m also find a tool that does the transcript so we can publish both of that. And I wish you all a wonderful week and hope to see you the next time when we have something like this exciting to propose. Bye everybody.
Andrea Roenning:
Thank you.
JuanMa Garrido:
Thank you.
Birgit Pauli-Haack:
Bye.
JuanMa Garrido:
Thank you. Very good. Thank you Andrea.
Feedback collected from the community will help refine the proposal and inform next steps for implementation.
