Using multiple stylesheets per block

Prior to WordPress 5.9, each blockBlock 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. could (but not required to) have a stylesheet attached to it. The way blocks could register a stylesheet was by adding a style and/or editorStyle string in their block.json file.

In WordPress 5.9 we’re enhancing that behavior to allow using multiple stylesheets to be registered for each block. This change can benefit both block developers and theme developers, further reducing the total page-weight by only loading styles for blocks that exist on a page.

Blocks will now be able to register multiple stylesheets, and load styles from other blocks when needed. Themes will be able to add styles on a per-block basis instead of loading monolithic stylesheets that are force-loaded anywhere. This has a greater impact on block themes where stylesheets loading is optimised based on the page & layout contents, but can also be used by classic themes.

Usage for block developers

The style and editorStyle properties inside a block.json file can now be either a string, or an array of strings. Each string can be the handle of a previously registered stylesheet, or a path relative to the block.json file’s path, prefixed with file:./.

If you already have a block that uses a string, you needn’t worry. Everything will continue to work as expected. This is not a breaking change as the values can be either an array or a string, to maintain backward-compatibility.

This allows for complex blocks to reuse styles they need from other blocks without the need to duplicate those styles. For example, the comment-form block in WordPress 5.9 doesn’t need to duplicate the button block’s styles, and can instead reuse these styles by adding them to the block.json file:

{
 	"style": [
		"wp-block-post-comments-form",
		"wp-block-buttons",
		"wp-block-button"
	]
}

The same applies to the editorStyle value: Block developers can now define an array of styles, using the same format as the style value.

Usage for theme developers

Theme developers can also register stylesheets on a per-block basis. This way, no unnecessary styles will be rendered on a page unless the block is rendered (assuming the theme is a block-theme, or has opted-in to load separate stylesheets in the case of classic themes).

To do that, a new wp_enqueue_block_style() function was introduced.

The wp_enqueue_block_style function

The wp_enqueue_block_style function accepts 2 arguments, both of which are required:

$block_name

(string, required)

The name of the block – including its prefix/domain. For example the block_name of the paragraph block is core/paragraph.

$args

(array, required)

The arguments are the same used in the wp_enqueue_style function:

$args = array(
	'handle' => 'my-theme-p-styles',
	'src'    => get_theme_file_uri( 'styles/blocks/paragraph.css' ),
	...
);

In addition to the default wp_enqueue_style arguments, you can also add a path argument. This will allow WordPress to inline small assets when possible – if the theme opts-in to that behavior.

Example

Registering an extra stylesheet for the site-title block from a theme:

add_action( 'after_setup_theme', function() {
	// Same args used for wp_enqueue_style().
	$args = array(
		'handle' => 'my-theme-site-title',
		'src'    => get_theme_file_uri( 'assets/blocks/site-title.css' ),
	);

	// Add "path" to allow inlining asset if the theme opts-in.
	$args['path'] = get_theme_file_path( 'assets/blocks/site-title.css' );

	// Enqueue asset.
	wp_enqueue_block_style( 'core/site-title', $args );
} );

WordPress 5.9 enhances the way stylesheets for blocks get loaded. Though these changes have not been ported to block scripts yet, in future releases we plan to sync the two APIs, so block scripts can take advantage of them as well.

props @gziolo for reviewing this post.

#dev-notes, #developer-documentation

Check out & contribute to the updated Gutenberg Examples

This week, a major portion of the work to update the Gutenberg Examples repository was completed. The repository blockBlock 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. examples, while accurate, were out of date and didn’t reflect the most current approach to block registration.

These examples can be used in many ways. You can read through them to learn how to create blocks, check out the repository and modify them to see how they work, or use them as a starting point for your own blocks.

All example blocks now use block metadata files and leverage the most recent version of the Block API. Updates were also made to the developer experience to introduce ESlint and Prettier configurations that can be used by IDEs, and to leverage the most recent version of the @wordpress/scripts package.

Share your examples

While the existing examples cover a lot of topics and use cases, it would be great to expand the list and help more folks do more with blocks. In particular, examples covering more advanced block related topics or topics that are not strictly related to creating blocks but still part of the GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ developer toolkit, such as SlotFill, are very much needed.

If you’re looking for a way to contribute and grow community knowledge, please consider opening an issue or pull request with your example suggestion.

Special thanks to @mkaz and @gziolo for their help with code review and to @annezazu, @mkaz, @chanthaboune, @sparklingrobots, and @audrasjb for reviewing this post

#developer-documentation, #gutenberg

Docs Focus role & workflow during WordPress release cycle

This is a summary of a discussion which happened during previous Docs Team meetings and also a proposal for WordPress 5.8.

During the previous weekly Docs team meetings, a discussion started about how the Documentation team could be better involved during WordPress release cycles.

In recent years, all new versions of WordPress have had a person responsible for the “Docs” focus (@justinahinon for 5.3 and 5.5, @audrasjb for 5.4 and 5.7, @sncoker, @m_butcher and their cohort for 5.6). But even if all the dev notesdev note Each important change in WordPress Core is documented in a developers note, (usually called dev note). Good dev notes generally include: a description of the change; the decision that led to this change a description of how developers are supposed to work with that change. Dev notes are published on Make/Core blog during the beta phase of WordPress release cycle. Publishing dev notes is particularly important when plugin/theme authors and WordPress developers need to be aware of those changes.In general, all dev notes are compiled into a Field Guide at the beginning of the release candidate phase. and the Field GuideField guide The field guide is a type of blogpost published on Make/Core during the release candidate phase of the WordPress release cycle. The field guide generally lists all the dev notes published during the beta cycle. This guide is linked in the about page of the corresponding version of WordPress, in the release post and in the HelpHub version page. (which are the main tasks of the Docs Focus) are published, the Docs team pointed out that it’s difficult for them to make sure all the end-user documentation (HelpHub) and the developer documentation (DevHub) are up to date after a new version is released.

WordPress release Docs Focus

@milana_cap (@zzap on SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/.) is the Docs Focus Lead for WordPress 5.8. The role of Docs Focus lead includes the responsibilities listed below. For each responsibility, one or more deputies will help the release Docs Focus lead but Milana Cap will remain the unique Docs reference person for the Release squad.

Developers notes wrangling on Make/CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.

  • Keep track of changes within the release that require dev notes
    (changes that require a dev notedev note Each important change in WordPress Core is documented in a developers note, (usually called dev note). Good dev notes generally include: a description of the change; the decision that led to this change a description of how developers are supposed to work with that change. Dev notes are published on Make/Core blog during the beta phase of WordPress release cycle. Publishing dev notes is particularly important when plugin/theme authors and WordPress developers need to be aware of those changes.In general, all dev notes are compiled into a Field Guide at the beginning of the release candidate phase. must be labelled with the needs-dev-note workflow keyword)
  • Ensure all dev notes are written with enough time to proofread, reviewed, and published prior to the field guide (which is published by the Docs Focus lead at the same time as release candidaterelease candidate One of the final stages in the version release cycle, this version signals the potential to be a final release to the public. Also see alpha (beta). 1)
  • Coordinate with the participants of those tickets with the best understanding of the changes (the committercommitter A developer with commit access. WordPress has five lead developers and four permanent core developers with commit access. Additionally, the project usually has a few guest or component committers - a developer receiving commit access, generally for a single release cycle (sometimes renewed) and/or for a specific component., component maintainers, the contributor who owns the ticketticket Created for both bug reports and feature development on the bug tracker.) to draft dev notes
  • If a ticket participant is not available to write a dev note, finding someone to write one, or writing one yourself
  • Proofread and review dev notes as they are available from the Documentation Wrangling team
    • Verify code examples
    • Make suggestions for additional examples
    • Ensure the developer notes accurately and thoroughly describe the problem, solution, and identify proper usage of the changes

End-user documentation wrangling on HelpHub

  • Keep track of changes within the release that require changes on HelpHub
    (changes that require HelpHub changes (whether it’s a new page or just an update on existing ones) must be labelled with the needs-codex workflow keyword)
  • Ensure any documentation pages required for new features are created before the release
  • Ensure any existing documentation page for changes on existing features are ready to be updated (the day of the final release)
  • Write and publish the release version page on HelpHub
  • Update WordPress versions page on the Codex

Developer documentation wrangling on DevHub

  • Keep track of changes within the release that require changes on DevHub
    (changes that require DevHub changes –whether it’s a new page or just an update on existing ones– must be labelled with the needs-docs workflow keyword)
  • Ensure any documentation sections required for new features are ready to be updated (they are updated a few days after the final release, once the DevHub automatic parser has synchronized the documentation)
    • “More information” sections on DevHub (example)
    • BlockBlock 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. editor Developer Docs
  • Ensure any existing documentation sections for changes on existing features are ready to be updated (they are also updated a few days after the final release)
    • “More information” sections on DevHub
    • Block editor Developer Docs

Workflow

A new spreadsheet will be created by the docs focus lead. The previous spreadsheet was built for dev notes over all, with a simple “HelpHub” column. For WordPress 5.8, the Docs team proposed to use a tab for each responsibility: Dev notes, HelpHub and DevHub, so they can be equally wrangled. Also, Core changes from TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. will be separated from Block Editor changes from GitHubGitHub GitHub is a website that offers online implementation of git repositories that can 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 be the repository owner. https://github.com/.

Reviewed by @milana_cap and @jeffpaul.

#5-8, #developer-documentation, #devhub, #docs, #documentation, #helphub

Block Editor Handbook: restructuring project update (25 January)

This is the second update for the project to restructure the developer documentation of the blockBlock 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. editor. You can find the first update here.

The last two weeks we have been working on improving the documentation homepage. The PR for this has recently been merged, and the block editor now has a homepage with an improved structure. You can give a look at it here.

The next step for the next two weeks is to improve the table of contents of the documentation. The aim is to make it more consistent, and more complete.

The main exit to track changes to the table of contents is here. All contributions and ideas are welcome.

Thanks to all the people who contributed to the project; props to @mkaz @youknowriad @milana_cap @annezazu @paaljoachim.

#block-editor, #developer-documentation

Block Editor Handbook: restructuring project update (15 January)

This post is the first in a series that will be published regularly on the Make/CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. blogblog (versus network, site). The purpose of this series is to keep everyone up to date on the progress of the BlockBlock 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. Editor Handbook restructuring project.

Currently, we are working on improving the handbook’s homepage. The goal is to make this page a real “Getting Started” page.

Someone coming to this page should be able to have a good overview of what the block editor is all about. They should also be able to find references to how to extend the block editor, how to contribute to it, or to the documentation of its main concepts.

The issue related to the handbook homepage improvement is here and here is the corresponding pull request.

Thanks to all the contributors who helped on the project this week 👏🏻.

#block-editor, #developer-documentation