Documentation request: reusable blocks

[benlk]

Describe the bug
The Gutenberg Handbook has no non-code definitions of reusable block functionality.

To Reproduce
Search https://wordpress.org/gutenberg/?s=reusable

Expected behavior
The Gutenberg Handbook should explain reusable blocks:

• what they are
• how they're made
• how they're stored and updated
• how they can be used in posts

Screenshots
If applicable, add screenshots to help explain your problem.

Context

Reusable blocks are a major selling point of Gutenberg, aiming to replace WordPress widgets. It would be nice to have a definition of the term in the Gutenberg docs rather than relying on media coverage and third-party documentation for definitional information.

[chrisvanpatten]

Thanks @benlk — this will definitely be included in our Gutenberg user documentation which is being outlined over in #10911.

[benlk]

There is still no documentation for reusable blocks, either in https://wordpress.org/support/article/wordpress-editor/#blocks or this repo's https://developer.wordpress.org/block-editor/ . What's the best way to contribute that?

[skorasaurus]

_@benlk I had wondered about that myself a couple weeks ago, went down a brief rabbit hole and ended up joining the WordPress Slack and asked in there; since no company is paying anyone full-time to improve community documentation and recent migration of help documentation from the codex to helphub; there's not a clear onboarding process or window for people to contribute) for it..

I also found the documentation on reusable blocks to be lacking; while trying to find resources to share with co-workers and so I could learn (and train them).

As of now, all that I've found is a brief section at https://developer.wordpress.org/block-editor/principles/key-concepts/#reusable-blocks

As a result, I wrote up what I know and share it below:

Resuable Blocks:

A block or series of blocks that you can access and insert multiple times in a WordPress site;
anticipated use cases (e.g. A heading whose content and custom styled color is the same and reused multiple pages of the site; sidebar widgets that would appear on every page (the widgets is planned to be available, but not yet possible, in Gutenberg)

• can be used across different post types (e.g. page and post)

• Note if you change a reusable block and save it; the content and style that you changed will also be applied in all other instances of that reusable block!

• Capabilities to access and edit reusable blocks are currently tied into same capabilities used accessing & editing posts of the post_type 'post'.
  (If we give a user permissions to edit a reusable block, we must give them access to edit all posts of the post_type 'post' ; see https://core.trac.wordpress.org/ticket/45423

• If you need to create structure (a block consisting of header, paragraph, and an image ) that is very similar across multiple pages but the content is slightly different across those pages or posts, you can do the following:

create a 'skeleton' that will have shared characteristics on multiple pages;
save it as a reusable block.
then on other pages:
into a page, then click on the block's properties (three dots)
and click "convert to regular block"; it's no longer reusable and now when you edit within this block; your edits will only appear on this page/post.

[noisysocks]

Hi @skorasaurus, that looks pretty good to me. Are you able to submit a PR which updates the documentation with what you've written here?

https://github.com/WordPress/gutenberg/blob/master/docs/designers-developers/key-concepts.md

[mkaz]

Closed in #21843

[benlk]

Will the content of that PR show up at https://developer.wordpress.org/block-editor/principles/key-concepts/#reusable-blocks ?

[mkaz]

@benlk yes, eventually. Right now the docs are pinned to the wp/5.4 tag so they match what was released in core, but I think this is probably not the right approach.

[bph]

Just to make sure we are not working on the same thing. During the last three weeks of recruiting people for the block editor end user documentation team, Laura Cristiano has raised a hand to create a tutorial for reusable blocks. It will link from this page: https://wordpress.org/support/article/wordpress-editor/
or around there

[skorasaurus]

Great point and thanks for checking in @bph.

Thanks for your work on coordinating the end user documentation.

This clarification of where documentation should live is really helpful and guided my response.

Initially, there wasn't any documentation on reusable blocks in the editor handbook or in the end-user documentation; so I wrote something up in the mean time that would end up partially fulfilling the user documentation and the block handbook (I'm sure it could be improved but it was a start) and future edits can keep that mind.

I admit that I was a little too discouraged to follow up with the docs team to get it into the user documentation and have limited time to participate.

(This is a tangent although there is already some documentation written at wordPress.com on reusable blocks in case you weren't already aware; maybe some of that could be reused although that's probably been already though of.

[annezazu]

Just looping back in case it's helpful that I published a v1 for reusable blocks here: https://wordpress.org/support/article/reusable-blocks/ Welcome guidance on where best to cross link but wanted to get something out ahead of 5.8 and the new modal for creation of reusable blocks.