Add automated core blocks documentation #36183
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
mkaz
requested review from
ajitbohra,
nerrad,
ntwb and
oandregal
as code owners
|
Size Change: 0 B Total Size: 1.13 MB ℹ️ View Unchanged
|
|
@oandregal I think this is all ready. I added the process to the I'd like to see the block.json and theme.json documentation get generated from the schema definitions (#36278 and #36279) so we'll probably need to address when those go in. |
mkaz
force-pushed
the
docs/gen-blocks-list
branch
from
9d49140
to
48b6c82
Compare
|
Maybe we should add the values of the supports keys. For example the Custom HTML Block has this supports values which are missing: Should we add the type (string, boolean, number, ...) of the attributes? It would increase the readability if the attributes and supports values are rendered as a list. |
|
@Soean yeh, I was wondering if we should include the types and values. I tried this format because rendering supports and attributes as a list would make each entry and the entire page too long and difficult to navigate. What do you think of each block on its own page and an index page to link them all? Then the details page for each block can include more data and info. |
mkaz
force-pushed
the
docs/gen-blocks-list
branch
2 times, most recently
from
442e96f
to
e6b43f5
Compare
|
Hey, for color supports there's one tricky thing: text & background are enabled by default (if there's a |
mkaz
force-pushed
the
docs/gen-blocks-list
branch
4 times, most recently
from
0246430
to
737461f
Compare
|
Good catch @oandregal - this also highlighted that other disabled supports were not shown, for example I tweaked the formatting and added the disabled values as strike outs, so it shows that they are explicitly disabled. You can see the new docs page rendered here. |
|
I was thinking that background and text (color) should be listed in the block supports when the block has a color key and does not disable them explicitly. For example, in the paragraph block we should show that it supports background, text, and link for color (at the moment, we only show link). |
|
@oandregal Got it. I updated the script to augment supports with the default colors if specified. 👍 |
It's a bit confusing when you look at the document without the context of this PR. Should we maybe include an |
mkaz
force-pushed
the
docs/gen-blocks-list
branch
from
32a72c0
to
2e420d1
Compare
- Creates a new script to generate core-blocks document - Lists all core blocks with supports, attributes - Add to build process
Adds a function to augment the color supports if specified to include background and text, if not disabled. Plus a few minor fixes to support Windows.
mkaz
force-pushed
the
docs/gen-blocks-list
branch
from
2e420d1
to
4440532
Compare
|
Good suggestion @gziolo, I added a callout at the top to explain the strikethrough. 👍 |
gziolo
approved these changes
Dec 20, 2021
There was a problem hiding this comment.
It looks like a good first step. The produced output is helpful enough to expose it to the Block Editor Handbook for initial feedback.
As a follow-up, it would be nice to create a simple unit test that uses some test fixtures to validate the output produced by readBlockJSON. This way, we will get a nice way to speed up iterations on the documentation's presentation layer.
|
Link to the handbook: https://developer.wordpress.org/block-editor/reference-guides/core-blocks/ |
|
Now that it is available in the Block Editor Handbook, it might be great to include a new field in {
"since": "WordPress 5.9.0"
}or {
"since": "Gutenberg 10.7 (experimental)"
}This would a similar role to |
This was referenced Dec 21, 2021
11 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
Adds a script to generate core block documentation reading all the blocks in the
packages/block-libraryand using theirblock.jsonproperties to generate the list.Done:
docs:buildcommandHow has this been tested?
node bin/api-docs/gen-block-lib-list.jsdocs/reference-guides/core-blocks.mdScreenshots
Types of changes