Skip to content

Commit 87c08e6

Browse files
carolinant-hamano
carolinan
and
t-hamano
authored
Docs: Add parent and experimental status to the core block reference (#48269)
* Docs: Add parent and experimental status to the core block reference page * Add explanation for the Experimental keyword. --------- Co-authored-by: Aki Hamano <[email protected]>
1 parent 075d937 commit 87c08e6

File tree

2 files changed

+40
-6
lines changed

2 files changed

+40
-6
lines changed

‎bin/api-docs/gen-block-lib-list.js‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -155,14 +155,20 @@ function readBlockJSON( filename ) {
155155
? processObjWithInnerKeys( augmentSupports( blockjson.supports ) )
156156
: [];
157157
const attributes = getTruthyKeys( blockjson.attributes );
158+
const parent = blockjson.parent
159+
? '\n' + `- **Parent:** ${ blockjson.parent.join( ', ' ) }`
160+
: '';
161+
const experimental = blockjson.__experimental
162+
? '\n' + `- **Experimental:** ${ blockjson.__experimental }`
163+
: '';
158164

159165
return `
160166
## ${ blockjson.title }
161167
162168
${ blockjson.description } ([Source](${ sourcefile }))
163169
164-
- **Name:** ${ blockjson.name }
165-
- **Category:** ${ blockjson.category }
170+
- **Name:** ${ blockjson.name }${ experimental }
171+
- **Category:** ${ blockjson.category }${ parent }
166172
- **Supports:** ${ supportsList.sort().join( ', ' ) }
167173
- **Attributes:** ${ attributes.sort().join( ', ' ) }
168174
`;

‎docs/reference-guides/core-blocks.md‎

Lines changed: 32 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
# Core Blocks Reference
22

3-
This page lists the core blocks included in the block-library package.
3+
This page lists the blocks included in the block-library package.
4+
5+
- Items marked with a strikeout (~~strikeout~~) are explicitly disabled.
6+
- Blocks marked with **Experimental:** true are only available when Gutenberg is active.
7+
- Blocks marked with **Experimental:** fse are only available in the Site Editor.
48

5-
<div class="callout callout-info">
6-
Items marked with a strikeout (~~strikeout~~) are explicitly disabled.
7-
</div>
89

910
<!-- START TOKEN Autogenerated - DO NOT EDIT -->
1011

@@ -50,6 +51,7 @@ Prompt visitors to take action with a button-style link. ([Source](https://githu
5051

5152
- **Name:** core/button
5253
- **Category:** design
54+
- **Parent:** core/buttons
5355
- **Supports:** anchor, color (background, gradients, text), shadow, spacing (padding), typography (fontSize, lineHeight), ~~alignWide~~, ~~align~~, ~~reusable~~
5456
- **Attributes:** backgroundColor, gradient, linkTarget, placeholder, rel, text, textAlign, textColor, title, url, width
5557

@@ -95,6 +97,7 @@ A single column within a columns block. ([Source](https://github.com/WordPress/g
9597

9698
- **Name:** core/column
9799
- **Category:** design
100+
- **Parent:** core/columns
98101
- **Supports:** anchor, color (background, gradients, link, text), spacing (blockGap, padding), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~
99102
- **Attributes:** allowedBlocks, templateLock, verticalAlignment, width
100103

@@ -112,6 +115,7 @@ Display content in multiple columns, with blocks added to each column. ([Source]
112115
This block is deprecated. Please use the Avatar block instead. ([Source](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/comment-author-avatar))
113116

114117
- **Name:** core/comment-author-avatar
118+
- **Experimental:** fse
115119
- **Category:** theme
116120
- **Supports:** anchor, color (background, ~~text~~), spacing (margin, padding), ~~html~~, ~~inserter~~
117121
- **Attributes:** height, width
@@ -167,6 +171,7 @@ Contains the block elements used to display a comment, like the title, date, aut
167171

168172
- **Name:** core/comment-template
169173
- **Category:** design
174+
- **Parent:** core/comments
170175
- **Supports:** align, anchor, spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~
171176
- **Attributes:**
172177

@@ -185,6 +190,7 @@ Displays a paginated navigation to next/previous set of comments, when applicabl
185190

186191
- **Name:** core/comments-pagination
187192
- **Category:** theme
193+
- **Parent:** core/comments
188194
- **Supports:** align, anchor, color (background, gradients, link, text), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~
189195
- **Attributes:** paginationArrow
190196

@@ -194,6 +200,7 @@ Displays the next comment's page link. ([Source](https://github.com/WordPress/gu
194200

195201
- **Name:** core/comments-pagination-next
196202
- **Category:** theme
203+
- **Parent:** core/comments-pagination
197204
- **Supports:** anchor, color (background, gradients, ~~text~~), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~
198205
- **Attributes:** label
199206

@@ -203,6 +210,7 @@ Displays a list of page numbers for comments pagination. ([Source](https://githu
203210

204211
- **Name:** core/comments-pagination-numbers
205212
- **Category:** theme
213+
- **Parent:** core/comments-pagination
206214
- **Supports:** anchor, color (background, gradients, ~~text~~), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~
207215
- **Attributes:**
208216

@@ -212,6 +220,7 @@ Displays the previous comment's page link. ([Source](https://github.com/WordPres
212220

213221
- **Name:** core/comments-pagination-previous
214222
- **Category:** theme
223+
- **Parent:** core/comments-pagination
215224
- **Supports:** anchor, color (background, gradients, ~~text~~), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~
216225
- **Attributes:** label
217226

@@ -238,6 +247,7 @@ Add an image or video with a text overlay. ([Source](https://github.com/WordPres
238247
Hide and show additional content. ([Source](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/details))
239248

240249
- **Name:** core/details
250+
- **Experimental:** true
241251
- **Category:** text
242252
- **Supports:** align (full, wide), color (background, gradients, link, text), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~
243253
- **Attributes:** showContent, summary
@@ -302,6 +312,7 @@ Create a link that always points to the homepage of the site. Usually not necess
302312

303313
- **Name:** core/home-link
304314
- **Category:** design
315+
- **Parent:** core/navigation
305316
- **Supports:** anchor, typography (fontSize, lineHeight), ~~html~~, ~~reusable~~
306317
- **Attributes:** label
307318

@@ -356,6 +367,7 @@ Create a list item. ([Source](https://github.com/WordPress/gutenberg/tree/trunk/
356367

357368
- **Name:** core/list-item
358369
- **Category:** text
370+
- **Parent:** core/list
359371
- **Supports:** typography (fontSize, lineHeight), ~~className~~
360372
- **Attributes:** content, placeholder
361373

@@ -410,6 +422,7 @@ Add a page, link, or another item to your navigation. ([Source](https://github.c
410422

411423
- **Name:** core/navigation-link
412424
- **Category:** design
425+
- **Parent:** core/navigation
413426
- **Supports:** typography (fontSize, lineHeight), ~~html~~, ~~reusable~~
414427
- **Attributes:** description, id, isTopLevelLink, kind, label, opensInNewTab, rel, title, type, url
415428

@@ -419,6 +432,7 @@ Add a submenu to your navigation. ([Source](https://github.com/WordPress/gutenbe
419432

420433
- **Name:** core/navigation-submenu
421434
- **Category:** design
435+
- **Parent:** core/navigation
422436
- **Supports:** ~~html~~, ~~reusable~~
423437
- **Attributes:** description, id, isTopLevelItem, kind, label, opensInNewTab, rel, title, type, url
424438

@@ -428,6 +442,7 @@ Separate your content into a multi-page experience. ([Source](https://github.com
428442

429443
- **Name:** core/nextpage
430444
- **Category:** design
445+
- **Parent:** core/post-content
431446
- **Supports:** ~~className~~, ~~customClassName~~, ~~html~~
432447
- **Attributes:**
433448

@@ -446,6 +461,7 @@ Displays a page inside a list of all pages. ([Source](https://github.com/WordPre
446461

447462
- **Name:** core/page-list-item
448463
- **Category:** widgets
464+
- **Parent:** core/page-list
449465
- **Supports:** ~~html~~, ~~inserter~~, ~~lock~~, ~~reusable~~
450466
- **Attributes:** hasChildren, id, label, link, title
451467

@@ -499,6 +515,7 @@ The author name. ([Source](https://github.com/WordPress/gutenberg/tree/trunk/pac
499515
This block is deprecated. Please use the Comments block instead. ([Source](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/post-comment))
500516

501517
- **Name:** core/post-comment
518+
- **Experimental:** fse
502519
- **Category:** theme
503520
- **Supports:** ~~html~~, ~~inserter~~
504521
- **Attributes:** commentId
@@ -508,6 +525,7 @@ This block is deprecated. Please use the Comments block instead. ([Source](https
508525
Display a post's comments count. ([Source](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/post-comments-count))
509526

510527
- **Name:** core/post-comments-count
528+
- **Experimental:** fse
511529
- **Category:** theme
512530
- **Supports:** anchor, color (background, gradients, text), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~
513531
- **Attributes:** textAlign
@@ -526,6 +544,7 @@ Display a post's comments form. ([Source](https://github.com/WordPress/gutenberg
526544
Displays the link to the current post comments. ([Source](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/post-comments-link))
527545

528546
- **Name:** core/post-comments-link
547+
- **Experimental:** fse
529548
- **Category:** theme
530549
- **Supports:** anchor, color (background, link, ~~text~~), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~
531550
- **Attributes:** textAlign
@@ -581,6 +600,7 @@ Contains the block elements used to render a post, like the title, date, feature
581600

582601
- **Name:** core/post-template
583602
- **Category:** theme
603+
- **Parent:** core/query
584604
- **Supports:** align (full, wide), anchor, color (background, gradients, link, text), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~
585605
- **Attributes:**
586606

@@ -598,6 +618,7 @@ Post terms. ([Source](https://github.com/WordPress/gutenberg/tree/trunk/packages
598618
Show minutes required to finish reading the post. ([Source](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/post-time-to-read))
599619

600620
- **Name:** core/post-time-to-read
621+
- **Experimental:** true
601622
- **Category:** theme
602623
- **Supports:** color (background, gradients, text), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~
603624
- **Attributes:** textAlign
@@ -644,6 +665,7 @@ Contains the block elements used to render content when no query results are fou
644665

645666
- **Name:** core/query-no-results
646667
- **Category:** theme
668+
- **Parent:** core/query
647669
- **Supports:** align, anchor, color (background, gradients, link, text), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~
648670
- **Attributes:**
649671

@@ -653,6 +675,7 @@ Displays a paginated navigation to next/previous set of posts, when applicable.
653675

654676
- **Name:** core/query-pagination
655677
- **Category:** theme
678+
- **Parent:** core/query
656679
- **Supports:** align, anchor, color (background, gradients, link, text), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~
657680
- **Attributes:** paginationArrow
658681

@@ -662,6 +685,7 @@ Displays the next posts page link. ([Source](https://github.com/WordPress/gutenb
662685

663686
- **Name:** core/query-pagination-next
664687
- **Category:** theme
688+
- **Parent:** core/query-pagination
665689
- **Supports:** anchor, color (background, gradients, ~~text~~), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~
666690
- **Attributes:** label
667691

@@ -671,6 +695,7 @@ Displays a list of page numbers for pagination ([Source](https://github.com/Word
671695

672696
- **Name:** core/query-pagination-numbers
673697
- **Category:** theme
698+
- **Parent:** core/query-pagination
674699
- **Supports:** anchor, color (background, gradients, ~~text~~), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~
675700
- **Attributes:**
676701

@@ -680,6 +705,7 @@ Displays the previous posts page link. ([Source](https://github.com/WordPress/gu
680705

681706
- **Name:** core/query-pagination-previous
682707
- **Category:** theme
708+
- **Parent:** core/query-pagination
683709
- **Supports:** anchor, color (background, gradients, ~~text~~), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~
684710
- **Attributes:** label
685711

@@ -779,6 +805,7 @@ Display an icon linking to a social media profile or site. ([Source](https://git
779805

780806
- **Name:** core/social-link
781807
- **Category:** widgets
808+
- **Parent:** core/social-links
782809
- **Supports:** anchor, ~~html~~, ~~reusable~~
783810
- **Attributes:** label, rel, service, url
784811

@@ -814,6 +841,7 @@ Create structured content in rows and columns to display information. ([Source](
814841
Summarize your post with a list of headings. Add HTML anchors to Heading blocks to link them here. ([Source](https://github.com/WordPress/gutenberg/tree/trunk/packages/block-library/src/table-of-contents))
815842

816843
- **Name:** core/table-of-contents
844+
- **Experimental:** true
817845
- **Category:** layout
818846
- **Supports:** color (background, gradients, link, text), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~
819847
- **Attributes:** headings, onlyIncludeCurrentPage

0 commit comments

Comments
 (0)