diff --git a/bin/api-docs/gen-block-lib-list.js b/bin/api-docs/gen-block-lib-list.js new file mode 100644 index 0000000000000..52add5e45a2d5 --- /dev/null +++ b/bin/api-docs/gen-block-lib-list.js @@ -0,0 +1,174 @@ +/** + * Generates core block documentation using block.json files. + * Reads from : packages/block-library/src + * Publishes to: docs/reference-guides/core-blocks.ms + */ + +/** + * External dependencies + */ +const path = require( 'path' ); +const glob = require( 'fast-glob' ); +const fs = require( 'fs' ); +const { keys } = require( 'lodash' ); +/** + * Path to root project directory. + * + * @type {string} + */ +const ROOT_DIR = path.resolve( __dirname, '../..' ); + +/** + * Path to packages directory. + * + * @type {string} + */ +const BLOCK_LIBRARY_DIR = path.resolve( + ROOT_DIR, + 'packages/block-library/src' +); + +/** + * Path to docs file. + * + * @type {string} + */ +const BLOCK_LIBRARY_DOCS_FILE = path.resolve( + ROOT_DIR, + 'docs/reference-guides/core-blocks.md' +); + +/** + * Start token for matching string in doc file. + * + * @type {string} + */ +const START_TOKEN = ''; + +/** + * Start token for matching string in doc file. + * + * @type {string} + */ +const END_TOKEN = ''; + +/** + * Regular expression using tokens for matching in doc file. + * Note: `.` does not match new lines, so [^] is used. + * + * @type {RegExp} + */ +const TOKEN_PATTERN = new RegExp( START_TOKEN + '[^]*' + END_TOKEN ); + +/** + * Returns list of keys, filtering out any experimental + * and wrapping keys with ~~ to strikeout false values. + * + * @type {Object} obj + * @return {string[]} Array of truthy keys + */ +function getTruthyKeys( obj ) { + return keys( obj ) + .filter( ( key ) => ! key.startsWith( '__exp' ) ) + .map( ( key ) => ( obj[ key ] ? key : `~~${ key }~~` ) ); +} + +/** + * Process list of object that may contain inner keys. + * For example: spacing( margin, padding ). + * + * @param {Object} obj + * @return {string[]} Array of keys (inner keys) + */ +function processObjWithInnerKeys( obj ) { + const rtn = []; + + const kvs = getTruthyKeys( obj ); + + kvs.forEach( ( key ) => { + if ( Array.isArray( obj[ key ] ) ) { + rtn.push( `${ key } (${ obj[ key ].sort().join( ', ' ) })` ); + } else if ( typeof obj[ key ] === 'object' ) { + const innerKeys = getTruthyKeys( obj[ key ] ); + rtn.push( `${ key } (${ innerKeys.sort().join( ', ' ) })` ); + } else { + rtn.push( key ); + } + } ); + return rtn; +} + +/** + * Augment supports with additional default props. + * + * The color support if specified defaults background and text, if + * not disabled. So adding { color: 'link' } support also brings along + * background and text. + * + * @param {Object} supports - keys supported by blokc + * @return {Object} supports augmented with defaults + */ +function augmentSupports( supports ) { + if ( 'color' in supports ) { + // If backgroud or text is not specified (true or false) + // then add it as true.a + if ( ! ( 'background' in supports.color ) ) { + supports.color.background = true; + } + if ( ! ( 'text' in supports.color ) ) { + supports.color.text = true; + } + } + return supports; +} + +/** + * Reads block.json file and returns markdown formatted entry. + * + * @param {string} filename + * + * @return {string} markdown + */ +function readBlockJSON( filename ) { + const blockjson = require( filename ); + + const supportsAugmented = augmentSupports( blockjson.supports ); + const supportsList = processObjWithInnerKeys( supportsAugmented ); + const attributes = getTruthyKeys( blockjson.attributes ); + + return ` +## ${ blockjson.title } + +${ blockjson.description } + +- **Name:** ${ blockjson.name } +- **Category:** ${ blockjson.category } +- **Supports:** ${ supportsList.sort().join( ', ' ) } +- **Attributes:** ${ attributes.sort().join( ', ' ) } +`; +} + +// Generate block docs. +// Note: The replace() is to translate Windows back to Unix for fast-glob. +const files = glob.sync( + path.join( BLOCK_LIBRARY_DIR, '*', 'block.json' ).replace( /\\/g, '/' ) +); + +let autogen = ''; + +files.forEach( ( file ) => { + const markup = readBlockJSON( file ); + autogen += markup; +} ); + +let docsContent = fs.readFileSync( BLOCK_LIBRARY_DOCS_FILE, { + encoding: 'utf8', + flag: 'r', +} ); + +// Add delimiters back. +autogen = START_TOKEN + '\n' + autogen + '\n' + END_TOKEN; +docsContent = docsContent.replace( TOKEN_PATTERN, autogen ); + +// write back out +fs.writeFileSync( BLOCK_LIBRARY_DOCS_FILE, docsContent, { encoding: 'utf8' } ); diff --git a/docs/manifest.json b/docs/manifest.json index ae6249b7fe724..0581a58e0fdbd 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -485,6 +485,12 @@ "markdown_source": "../docs/reference-guides/block-api/block-variations.md", "parent": "block-api" }, + { + "title": "Core Blocks Reference", + "slug": "core-blocks", + "markdown_source": "../docs/reference-guides/core-blocks.md", + "parent": "reference-guides" + }, { "title": "Filter Reference", "slug": "filters", diff --git a/docs/reference-guides/core-blocks.md b/docs/reference-guides/core-blocks.md new file mode 100644 index 0000000000000..cf17da4da1b20 --- /dev/null +++ b/docs/reference-guides/core-blocks.md @@ -0,0 +1,794 @@ +# Core Blocks Reference + +This page lists the core blocks included in the block-library package. + +
+Items marked with a strikeout (~~strikeout~~) are explicitly disabled. +
+ + + +## Archives + +Display a monthly archive of your posts. + +- **Name:** core/archives +- **Category:** widgets +- **Supports:** align, ~~html~~ +- **Attributes:** displayAsDropdown, showPostCounts + +## Audio + +Embed a simple audio player. + +- **Name:** core/audio +- **Category:** media +- **Supports:** align, anchor +- **Attributes:** autoplay, caption, id, loop, preload, src + +## Reusable block + +Create and save content to reuse across your site. Update the block, and the changes apply everywhere it’s used. + +- **Name:** core/block +- **Category:** reusable +- **Supports:** ~~customClassName~~, ~~html~~, ~~inserter~~ +- **Attributes:** ref + +## Button + +Prompt visitors to take action with a button-style link. + +- **Name:** core/button +- **Category:** design +- **Supports:** align, anchor, color (background, gradients, text), spacing (padding), typography (fontSize), ~~alignWide~~, ~~reusable~~ +- **Attributes:** backgroundColor, gradient, linkTarget, placeholder, rel, text, textColor, title, url, width + +## Buttons + +Prompt visitors to take action with a group of button-style links. + +- **Name:** core/buttons +- **Category:** design +- **Supports:** align (full, wide), anchor, spacing (blockGap, margin) +- **Attributes:** + +## Calendar + +A calendar of your site’s posts. + +- **Name:** core/calendar +- **Category:** widgets +- **Supports:** align +- **Attributes:** month, year + +## Categories + +Display a list of all categories. + +- **Name:** core/categories +- **Category:** widgets +- **Supports:** align, ~~html~~ +- **Attributes:** displayAsDropdown, showHierarchy, showOnlyTopLevel, showPostCounts + +## Code + +Display code snippets that respect your spacing and tabs. + +- **Name:** core/code +- **Category:** text +- **Supports:** anchor, color (background, gradients, text), spacing (margin, padding), typography (fontSize, lineHeight) +- **Attributes:** content + +## Column + +A single column within a columns block. + +- **Name:** core/column +- **Category:** text +- **Supports:** anchor, color (background, gradients, link, text), spacing (padding), ~~html~~, ~~reusable~~ +- **Attributes:** allowedBlocks, templateLock, verticalAlignment, width + +## Columns + +Display content in multiple columns, with blocks added to each column. + +- **Name:** core/columns +- **Category:** design +- **Supports:** align (full, wide), anchor, color (background, gradients, link, text), spacing (blockGap, margin, padding), ~~html~~ +- **Attributes:** isStackedOnMobile, verticalAlignment + +## Comment Author Avatar + +Add the avatar of this comment's author. + +- **Name:** core/comment-author-avatar +- **Category:** theme +- **Supports:** color (background, ~~text~~), spacing (margin, padding), ~~html~~ +- **Attributes:** height, width + +## Comment Author Name + +Add the author name of this comment. + +- **Name:** core/comment-author-name +- **Category:** theme +- **Supports:** color (background, gradients, link, text), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~ +- **Attributes:** isLink, linkTarget, textAlign + +## Comment Content + +Displays the contents of a comment. + +- **Name:** core/comment-content +- **Category:** theme +- **Supports:** color (background, gradients, link, text), spacing (padding), typography (fontSize, lineHeight), ~~html~~ +- **Attributes:** textAlign + +## Comment Date + +Add the date of this comment. + +- **Name:** core/comment-date +- **Category:** theme +- **Supports:** color (background, gradients, link, text), typography (fontSize, lineHeight), ~~html~~ +- **Attributes:** format, isLink + +## Comment Edit Link + +Displays a link to edit the comment in the WordPress Dashboard. This link is only visible to users with the edit comment capability. + +- **Name:** core/comment-edit-link +- **Category:** theme +- **Supports:** color (background, gradients, link, ~~text~~), typography (fontSize, lineHeight), ~~html~~ +- **Attributes:** linkTarget, textAlign + +## Comment Reply Link + +Displays a link to reply to a comment. + +- **Name:** core/comment-reply-link +- **Category:** theme +- **Supports:** color (background, gradients, link, ~~text~~), typography (fontSize, lineHeight), ~~html~~ +- **Attributes:** textAlign + +## Comment Template + +Contains the block elements used to render a comment, like the title, date, author, avatar and more. + +- **Name:** core/comment-template +- **Category:** design +- **Supports:** align, ~~html~~, ~~reusable~~ +- **Attributes:** + +## Comments Pagination + +Displays a paginated navigation to next/previous set of comments, when applicable. + +- **Name:** core/comments-pagination +- **Category:** theme +- **Supports:** align, color (background, gradients, link, text), ~~html~~, ~~reusable~~ +- **Attributes:** paginationArrow + +## Next Page + +Displays the next comments page link. + +- **Name:** core/comments-pagination-next +- **Category:** theme +- **Supports:** color (background, gradients, ~~text~~), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~ +- **Attributes:** label + +## Page Numbers + +Displays a list of page numbers for comments pagination. + +- **Name:** core/comments-pagination-numbers +- **Category:** theme +- **Supports:** ~~html~~, ~~reusable~~ +- **Attributes:** + +## Comments Query Loop + +An advanced block that allows displaying post comments based on different query parameters and visual configurations. + +- **Name:** core/comments-query-loop +- **Category:** theme +- **Supports:** align (full, wide), color (background, gradients, link, text), ~~html~~ +- **Attributes:** perPage, tagName + +## Cover + +Add an image or video with a text overlay — great for headers. + +- **Name:** core/cover +- **Category:** media +- **Supports:** align, anchor, color (~~background~~, ~~text~~), spacing (padding), ~~html~~ +- **Attributes:** allowedBlocks, alt, backgroundType, contentPosition, customGradient, customOverlayColor, dimRatio, focalPoint, gradient, hasParallax, id, isDark, isRepeated, minHeight, minHeightUnit, overlayColor, templateLock, url + +## Embed + +Add a block that displays content pulled from other sites, like Twitter or YouTube. + +- **Name:** core/embed +- **Category:** embed +- **Supports:** align +- **Attributes:** allowResponsive, caption, previewable, providerNameSlug, responsive, type, url + +## File + +Add a link to a downloadable file. + +- **Name:** core/file +- **Category:** media +- **Supports:** align, anchor +- **Attributes:** displayPreview, downloadButtonText, fileId, fileName, href, id, previewHeight, showDownloadButton, textLinkHref, textLinkTarget + +## Classic + +Use the classic WordPress editor. + +- **Name:** core/freeform +- **Category:** text +- **Supports:** ~~className~~, ~~customClassName~~, ~~reusable~~ +- **Attributes:** content + +## Gallery + +Display multiple images in a rich gallery. + +- **Name:** core/gallery +- **Category:** media +- **Supports:** align, anchor +- **Attributes:** allowResize, caption, columns, fixedHeight, ids, imageCrop, images, linkTarget, linkTo, shortCodeTransforms, sizeSlug + +## Group + +Combine blocks into a group. + +- **Name:** core/group +- **Category:** design +- **Supports:** align (full, wide), anchor, color (background, gradients, link, text), spacing (blockGap, padding), typography (fontSize, lineHeight), ~~html~~ +- **Attributes:** tagName, templateLock + +## Heading + +Introduce new sections and organize content to help visitors (and search engines) understand the structure of your content. + +- **Name:** core/heading +- **Category:** text +- **Supports:** __unstablePasteTextInline, align (full, wide), anchor, color (background, link, text), spacing (margin), typography (fontSize, lineHeight), ~~className~~ +- **Attributes:** content, level, placeholder, textAlign + +## Home Link + +Create a link that always points to the homepage of the site. Usually not necessary if there is already a site title link present in the header. + +- **Name:** core/home-link +- **Category:** design +- **Supports:** ~~html~~, ~~reusable~~ +- **Attributes:** label + +## Custom HTML + +Add custom HTML code and preview it as you edit. + +- **Name:** core/html +- **Category:** widgets +- **Supports:** ~~className~~, ~~customClassName~~, ~~html~~ +- **Attributes:** content + +## Image + +Insert an image to make a visual statement. + +- **Name:** core/image +- **Category:** media +- **Supports:** anchor, color (~~background~~, ~~text~~) +- **Attributes:** align, alt, caption, height, href, id, linkClass, linkDestination, linkTarget, rel, sizeSlug, title, url, width + +## Latest Comments + +Display a list of your most recent comments. + +- **Name:** core/latest-comments +- **Category:** widgets +- **Supports:** align, ~~html~~ +- **Attributes:** commentsToShow, displayAvatar, displayDate, displayExcerpt + +## Latest Posts + +Display a list of your most recent posts. + +- **Name:** core/latest-posts +- **Category:** widgets +- **Supports:** align, ~~html~~ +- **Attributes:** addLinkToFeaturedImage, categories, columns, displayAuthor, displayFeaturedImage, displayPostContent, displayPostContentRadio, displayPostDate, excerptLength, featuredImageAlign, featuredImageSizeHeight, featuredImageSizeSlug, featuredImageSizeWidth, order, orderBy, postLayout, postsToShow, selectedAuthor + +## List + +Create a bulleted or numbered list. + +- **Name:** core/list +- **Category:** text +- **Supports:** __unstablePasteTextInline, anchor, color (background, gradients, link, text), typography (fontSize, lineHeight), ~~className~~ +- **Attributes:** ordered, placeholder, reversed, start, type, values + +## Login/out + +Show login & logout links. + +- **Name:** core/loginout +- **Category:** theme +- **Supports:** className, typography (~~fontSize~~) +- **Attributes:** displayLoginAsForm, redirectToCurrent + +## Media & Text + +Set media and words side-by-side for a richer layout. + +- **Name:** core/media-text +- **Category:** media +- **Supports:** align (full, wide), anchor, color (background, gradients, link, text), ~~html~~ +- **Attributes:** align, focalPoint, href, imageFill, isStackedOnMobile, linkClass, linkDestination, linkTarget, mediaAlt, mediaId, mediaLink, mediaPosition, mediaSizeSlug, mediaType, mediaUrl, mediaWidth, rel, verticalAlignment + +## Unsupported + +Your site doesn’t include support for this block. + +- **Name:** core/missing +- **Category:** text +- **Supports:** ~~className~~, ~~customClassName~~, ~~html~~, ~~inserter~~, ~~reusable~~ +- **Attributes:** originalContent, originalName, originalUndelimitedContent + +## More + +Content before this block will be shown in the excerpt on your archives page. + +- **Name:** core/more +- **Category:** design +- **Supports:** ~~className~~, ~~customClassName~~, ~~html~~, ~~multiple~~ +- **Attributes:** customText, noTeaser + +## Navigation + +A collection of blocks that allow visitors to get around your site. + +- **Name:** core/navigation +- **Category:** theme +- **Supports:** align (full, wide), anchor, inserter, spacing (blockGap, units), typography (fontSize, lineHeight), ~~html~~ +- **Attributes:** __unstableLocation, backgroundColor, customBackgroundColor, customOverlayBackgroundColor, customOverlayTextColor, customTextColor, openSubmenusOnClick, overlayBackgroundColor, overlayMenu, overlayTextColor, ref, rgbBackgroundColor, rgbTextColor, showSubmenuIcon, textColor + +## Navigation Area + +Define a navigation area for your theme. The navigation block associated with this area will be automatically displayed. + +- **Name:** core/navigation-area +- **Category:** theme +- **Supports:** ~~html~~, ~~inserter~~ +- **Attributes:** area + +## Custom Link + +Add a page, link, or another item to your navigation. + +- **Name:** core/navigation-link +- **Category:** design +- **Supports:** ~~html~~, ~~reusable~~ +- **Attributes:** description, id, isTopLevelLink, kind, label, opensInNewTab, rel, title, type, url + +## Submenu + +Add a submenu to your navigation. + +- **Name:** core/navigation-submenu +- **Category:** design +- **Supports:** ~~html~~, ~~reusable~~ +- **Attributes:** description, id, isTopLevelItem, kind, label, opensInNewTab, rel, title, type, url + +## Page Break + +Separate your content into a multi-page experience. + +- **Name:** core/nextpage +- **Category:** design +- **Supports:** ~~className~~, ~~customClassName~~, ~~html~~ +- **Attributes:** + +## Page List + +Display a list of all pages. + +- **Name:** core/page-list +- **Category:** widgets +- **Supports:** ~~html~~, ~~reusable~~ +- **Attributes:** __unstableMaxPages + +## Paragraph + +Start with the building block of all narrative. + +- **Name:** core/paragraph +- **Category:** text +- **Supports:** __unstablePasteTextInline, anchor, color (background, link, text), typography (fontSize, lineHeight), ~~className~~ +- **Attributes:** align, content, direction, dropCap, placeholder + +## Pattern + +Show a block pattern. + +- **Name:** core/pattern +- **Category:** theme +- **Supports:** ~~html~~, ~~inserter~~ +- **Attributes:** slug + +## Post Author + +Add the author of this post. + +- **Name:** core/post-author +- **Category:** theme +- **Supports:** color (background, gradients, link, text), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~ +- **Attributes:** avatarSize, byline, showAvatar, showBio, textAlign + +## Post Comment (deprecated) + +This block is deprecated. Please use the Comments Query Loop block instead. + +- **Name:** core/post-comment +- **Category:** theme +- **Supports:** ~~html~~, ~~inserter~~ +- **Attributes:** commentId + +## Post Comments + +Display a post's comments. + +- **Name:** core/post-comments +- **Category:** theme +- **Supports:** align (full, wide), color (background, gradients, link, text), typography (fontSize, lineHeight), ~~html~~ +- **Attributes:** textAlign + +## Post Comments Count + +Display a post's comments count. + +- **Name:** core/post-comments-count +- **Category:** theme +- **Supports:** color (background, gradients, text), typography (fontSize, lineHeight), ~~html~~ +- **Attributes:** textAlign + +## Post Comments Form + +Display a post's comments form. + +- **Name:** core/post-comments-form +- **Category:** theme +- **Supports:** color (background, gradients, link, text), typography (fontSize, lineHeight), ~~html~~ +- **Attributes:** textAlign + +## Post Comments Link + +Displays the link to the current post comments. + +- **Name:** core/post-comments-link +- **Category:** theme +- **Supports:** color (background, link, ~~text~~), typography (fontSize, lineHeight), ~~html~~ +- **Attributes:** textAlign + +## Post Content + +Displays the contents of a post or page. + +- **Name:** core/post-content +- **Category:** theme +- **Supports:** align (full, wide), ~~html~~ +- **Attributes:** + +## Post Date + +Add the date of this post. + +- **Name:** core/post-date +- **Category:** theme +- **Supports:** color (background, gradients, link, text), typography (fontSize, lineHeight), ~~html~~ +- **Attributes:** format, isLink, textAlign + +## Post Excerpt + +Display a post's excerpt. + +- **Name:** core/post-excerpt +- **Category:** theme +- **Supports:** color (background, gradients, link, text), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~ +- **Attributes:** moreText, showMoreOnNewLine, textAlign + +## Post Featured Image + +Display a post's featured image. + +- **Name:** core/post-featured-image +- **Category:** theme +- **Supports:** align (center, full, left, right, wide), color (~~background~~, ~~text~~), spacing (margin, padding), ~~html~~ +- **Attributes:** height, isLink, scale, width + +## Post Navigation Link + +Displays the next or previous post link that is adjacent to the current post. + +- **Name:** core/post-navigation-link +- **Category:** theme +- **Supports:** typography (fontSize, lineHeight), ~~html~~, ~~reusable~~ +- **Attributes:** label, linkLabel, showTitle, textAlign, type + +## Post Template + +Contains the block elements used to render a post, like the title, date, featured image, content or excerpt, and more. + +- **Name:** core/post-template +- **Category:** design +- **Supports:** align, ~~html~~, ~~reusable~~ +- **Attributes:** + +## Post Terms + +Post terms. + +- **Name:** core/post-terms +- **Category:** theme +- **Supports:** color (background, gradients, link, text), typography (fontSize, lineHeight), ~~html~~ +- **Attributes:** separator, term, textAlign + +## Post Title + +Displays the title of a post, page, or any other content-type. + +- **Name:** core/post-title +- **Category:** theme +- **Supports:** align (full, wide), color (background, gradients, link, text), spacing (margin), typography (fontSize, lineHeight), ~~html~~ +- **Attributes:** isLink, level, linkTarget, rel, textAlign + +## Preformatted + +Add text that respects your spacing and tabs, and also allows styling. + +- **Name:** core/preformatted +- **Category:** text +- **Supports:** anchor, color (background, gradients, text), typography (fontSize, lineHeight) +- **Attributes:** content + +## Pullquote + +Give special visual emphasis to a quote from your text. + +- **Name:** core/pullquote +- **Category:** text +- **Supports:** align (full, left, right, wide), anchor, color (background, gradients, link, text), typography (fontSize, lineHeight) +- **Attributes:** citation, textAlign, value + +## Query Loop + +An advanced block that allows displaying post types based on different query parameters and visual configurations. + +- **Name:** core/query +- **Category:** theme +- **Supports:** align (full, wide), color (background, gradients, link, text), ~~html~~ +- **Attributes:** displayLayout, query, queryId, tagName + +## Pagination + +Displays a paginated navigation to next/previous set of posts, when applicable. + +- **Name:** core/query-pagination +- **Category:** design +- **Supports:** align, color (background, gradients, link, text), ~~html~~, ~~reusable~~ +- **Attributes:** paginationArrow + +## Next Page + +Displays the next posts page link. + +- **Name:** core/query-pagination-next +- **Category:** design +- **Supports:** color (background, gradients, ~~text~~), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~ +- **Attributes:** label + +## Page Numbers + +Displays a list of page numbers for pagination + +- **Name:** core/query-pagination-numbers +- **Category:** design +- **Supports:** ~~html~~, ~~reusable~~ +- **Attributes:** + +## Previous Page + +Displays the previous posts page link. + +- **Name:** core/query-pagination-previous +- **Category:** design +- **Supports:** color (background, gradients, ~~text~~), typography (fontSize, lineHeight), ~~html~~, ~~reusable~~ +- **Attributes:** label + +## Query Title + +Display the query title. + +- **Name:** core/query-title +- **Category:** theme +- **Supports:** align (full, wide), color (background, gradients, text), spacing (margin), typography (fontSize, lineHeight), ~~html~~ +- **Attributes:** level, textAlign, type + +## Quote + +Give quoted text visual emphasis. "In quoting others, we cite ourselves." — Julio Cortázar + +- **Name:** core/quote +- **Category:** text +- **Supports:** anchor, typography (fontSize, lineHeight) +- **Attributes:** align, citation, value + +## RSS + +Display entries from any RSS or Atom feed. + +- **Name:** core/rss +- **Category:** widgets +- **Supports:** align, ~~html~~ +- **Attributes:** blockLayout, columns, displayAuthor, displayDate, displayExcerpt, excerptLength, feedURL, itemsToShow + +## Search + +Help visitors find your content. + +- **Name:** core/search +- **Category:** widgets +- **Supports:** align (center, left, right), color (background, gradients, text), ~~html~~ +- **Attributes:** buttonPosition, buttonText, buttonUseIcon, label, placeholder, showLabel, width, widthUnit + +## Separator + +Create a break between ideas or sections with a horizontal separator. + +- **Name:** core/separator +- **Category:** design +- **Supports:** align (center, full, wide), anchor +- **Attributes:** color, customColor + +## Shortcode + +Insert additional custom elements with a WordPress shortcode. + +- **Name:** core/shortcode +- **Category:** widgets +- **Supports:** ~~className~~, ~~customClassName~~, ~~html~~ +- **Attributes:** text + +## Site Logo + +Display a graphic to represent this site. Update the block, and the changes apply everywhere it’s used. This is different than the site icon, which is the smaller image visible in your dashboard, browser tabs, etc used to help others recognize this site. + +- **Name:** core/site-logo +- **Category:** theme +- **Supports:** align, color (~~background~~, ~~text~~), ~~alignWide~~, ~~html~~ +- **Attributes:** isLink, linkTarget, width + +## Site Tagline + +Describe in a few words what the site is about. The tagline can be used in search results or when sharing on social networks even if it's not displayed in the theme design. + +- **Name:** core/site-tagline +- **Category:** theme +- **Supports:** align (full, wide), color (background, gradients, text), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~ +- **Attributes:** textAlign + +## Site Title + +Displays the name of this site. Update the block, and the changes apply everywhere it’s used. This will also appear in the browser title bar and in search results. + +- **Name:** core/site-title +- **Category:** theme +- **Supports:** align (full, wide), color (background, gradients, link, text), spacing (margin, padding), typography (fontSize, lineHeight), ~~html~~ +- **Attributes:** isLink, level, linkTarget, textAlign + +## Social Icon + +Display an icon linking to a social media profile or site. + +- **Name:** core/social-link +- **Category:** widgets +- **Supports:** ~~html~~, ~~reusable~~ +- **Attributes:** label, service, url + +## Social Icons + +Display icons linking to your social media profiles or sites. + +- **Name:** core/social-links +- **Category:** widgets +- **Supports:** align (center, left, right), anchor, spacing (blockGap, margin, units) +- **Attributes:** customIconBackgroundColor, customIconColor, iconBackgroundColor, iconBackgroundColorValue, iconColor, iconColorValue, openInNewTab, size + +## Spacer + +Add white space between blocks and customize its height. + +- **Name:** core/spacer +- **Category:** design +- **Supports:** anchor +- **Attributes:** height, width + +## Table + +Create structured content in rows and columns to display information. + +- **Name:** core/table +- **Category:** text +- **Supports:** align, anchor, color (background, gradients, text), typography (fontSize, lineHeight) +- **Attributes:** body, caption, foot, hasFixedLayout, head + +## Table of Contents + +Summarize your post with a list of headings. Add HTML anchors to Heading blocks to link them here. + +- **Name:** core/table-of-contents +- **Category:** layout +- **Supports:** ~~html~~ +- **Attributes:** onlyIncludeCurrentPage + +## Tag Cloud + +A cloud of your most used tags. + +- **Name:** core/tag-cloud +- **Category:** widgets +- **Supports:** align, ~~html~~ +- **Attributes:** numberOfTags, showTagCounts, taxonomy + +## Template Part + +Edit the different global regions of your site, like the header, footer, sidebar, or create your own. + +- **Name:** core/template-part +- **Category:** theme +- **Supports:** align, ~~html~~, ~~reusable~~ +- **Attributes:** area, slug, tagName, theme + +## Term Description + +Display the description of categories, tags and custom taxonomies when viewing an archive. + +- **Name:** core/term-description +- **Category:** theme +- **Supports:** align (full, wide), color (background, link, text), typography (fontSize, lineHeight), ~~html~~ +- **Attributes:** textAlign + +## Text Columns (deprecated) + +This block is deprecated. Please use the Columns block instead. + +- **Name:** core/text-columns +- **Category:** design +- **Supports:** ~~inserter~~ +- **Attributes:** columns, content, width + +## Verse + +Insert poetry. Use special spacing formats. Or quote song lyrics. + +- **Name:** core/verse +- **Category:** text +- **Supports:** anchor, color (background, gradients, link, text), spacing (padding), typography (fontSize, lineHeight) +- **Attributes:** content, textAlign + +## Video + +Embed a video from your media library or upload a new one. + +- **Name:** core/video +- **Category:** media +- **Supports:** align, anchor +- **Attributes:** autoplay, caption, controls, id, loop, muted, playsInline, poster, preload, src, tracks + + diff --git a/docs/toc.json b/docs/toc.json index ff630ba74f438..35186a8579a4c 100644 --- a/docs/toc.json +++ b/docs/toc.json @@ -194,6 +194,7 @@ } ] }, + { "docs/reference-guides/core-blocks.md": [] }, { "docs/reference-guides/filters/README.md": [ { "docs/reference-guides/filters/block-filters.md": [] }, diff --git a/package.json b/package.json index b93e9230ca28b..2078ef5998a24 100644 --- a/package.json +++ b/package.json @@ -237,7 +237,7 @@ "dev": "npm run build:packages && concurrently \"wp-scripts start\" \"npm run dev:packages\"", "dev:packages": "node ./bin/packages/watch.js", "distclean": "rimraf node_modules packages/*/node_modules", - "docs:build": "node ./docs/tool/index.js && node ./bin/api-docs/update-api-docs.js", + "docs:build": "node ./docs/tool/index.js && node ./bin/api-docs/update-api-docs.js && node ./bin/api-docs/gen-block-lib-list.js", "fixtures:clean": "rimraf \"test/integration/fixtures/blocks/*.+(json|serialized.html)\"", "fixtures:generate": "cross-env GENERATE_MISSING_FIXTURES=y npm run test-unit test/integration/full-content/ && npm run format test/integration/fixtures/blocks/*.json", "fixtures:regenerate": "npm run fixtures:clean && npm run fixtures:generate",