Create a block pattern for Block Documentation

[samxmunoz]

To ensure block documentation is more consistent and to expedite the process of creating block documentation, we will create a block pattern that includes the core components of most block documentation.

The content that should be included in the pattern would be:

• Intro
• Steps
• Block Toolbar
• Block Settings

and then a docs contributor could simply add that pattern into a new document and fill in the details.

• Create & group the entire documentation so it can be made into a block pattern
• Review with team
• Add to site as a block pattern

[samxmunoz]

I created the block pattern (template), it is ready for review before we actually add it as a pattern - also, who will we have to work with to add it as a pattern?

https://wordpress.org/support/?post_type=helphub_article&p=16058701&preview=true

@femkreations @colorful-tones @zzap

[colorful-tones]

A small nitpick and should not be a blocker, but it would be cool to put the Changelog in columns and save a few pixels of vertical space to get the "Top" and content side-by-side.

Also, there is a weird border around two sides of the Changelog. I would just remove all borders if possible.

This seems like it would be a great enhancement to expedite consistent doc creation. Nice work @samxmunoz

[samxmunoz]

@colorful-tones - I hear you, this was changelog block taken from another article & I think it as a standard had some extra padding up top - but I'm not 100% sure. I'll take a look!

[zzap]

Love the pattern. I say "Ship it!" 😅

[colorful-tones]

The "Top" link is added somehow with JavaScript. I do not know why it would be done that way and would recommend we take the opportunity to investigate and just incorporate the markup for the "Top" link directly into the pattern and then we can adjust the overall layout and spacing.

@zzap where is the codebase for the Docs site please?

[estelaris]

@samxmunoz and @colorful-tones don't worry too much about the changelog, there is a new design recommendation for it

[colorful-tones]

@estelaris sounds good! I did not want us to get too hung up on it. I agree, that this is ready to ship. Thanks @samxmunoz 👏

[zzap]

This is complete pattern

<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group"><!-- wp:paragraph {"align":"right","fontSize":"small"} -->
<p class="has-text-align-right has-small-font-size"><a href="https://wordpress.org/support/article/blocks/">Go to the List of Blocks</a></p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>Here you should briefly describe what the block does and italicize the block name. For example: The <em>latest comments block</em> displays the most recent comments readers have left on your blog.</p>
<!-- /wp:paragraph -->

<!-- wp:video {"autoplay":false,"id":16002189,"loop":false,"muted":false,"src":"https://wordpress.org/support/files/2022/09/HelpHub-RSS-Block-August-2022.mp4"} -->
<figure class="wp-block-video"><video controls src="https://wordpress.org/support/files/2022/09/HelpHub-RSS-Block-August-2022.mp4"></video><figcaption class="wp-element-caption">Replace this video with a demonstration of adding and editing the block</figcaption></figure>
<!-- /wp:video -->

<!-- wp:paragraph -->
<p>The&nbsp;{<em>block name} block</em>&nbsp;can be added to a page by clicking on the Add Block button. Alternatively, you can type /{blockname} and click on <em>{Block Name}</em>.</p>
<!-- /wp:paragraph -->

<!-- wp:image {"align":"center","id":15863326,"width":316,"height":186,"sizeSlug":"full","linkDestination":"media"} -->
<figure class="wp-block-image aligncenter size-full is-resized"><a href="https://wordpress.org/support/files/2019/03/Latest-Comments-HelpHub-SS-2.png"><img src="https://wordpress.org/support/files/2019/03/Latest-Comments-HelpHub-SS-2.png" alt="Add latest comments with the slash command" class="wp-image-15863326" width="316" height="186"/></a><figcaption class="wp-element-caption">Add {block name} with a Slash command.</figcaption></figure>
<!-- /wp:image -->

<!-- wp:paragraph {"style":{"color":{"background":"#e5f5fa"}}} -->
<p class="has-background" style="background-color:#e5f5fa">Detailed instructions on adding blocks can be found <a href="https://wordpress.org/support/article/adding-a-new-block/">here</a>.</p>
<!-- /wp:paragraph -->

<!-- wp:heading -->
<h2>Block Toolbar</h2>
<!-- /wp:heading -->

<!-- wp:paragraph -->
<p>Each block has its own block-specific controls that allow you to manipulate the block right in the editor. </p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p><strong>Transform to</strong></p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>You can transform a {Block Name} block into a Columns or a Group block {add other transform to options here}.&nbsp;</p>
<!-- /wp:paragraph -->

<!-- wp:image {"id":15878507,"width":307,"height":185,"sizeSlug":"full","linkDestination":"none"} -->
<figure class="wp-block-image size-full is-resized"><img src="https://wordpress.org/support/files/2022/08/Screen-Shot-2022-08-01-at-11.12.17-AM.png" alt="Transform tool in the Latest Comments block" class="wp-image-15878507" width="307" height="185"/></figure>
<!-- /wp:image -->

<!-- wp:paragraph -->
<p><strong>Block-moving tools</strong></p>
<!-- /wp:paragraph -->

<!-- wp:image {"id":15878513,"width":317,"height":78,"sizeSlug":"full","linkDestination":"none"} -->
<figure class="wp-block-image size-full is-resized"><img src="https://wordpress.org/support/files/2022/08/Screen-Shot-2022-08-01-at-11.14.47-AM.png" alt="Block moving tools in the Latest comments block" class="wp-image-15878513" width="317" height="78"/></figure>
<!-- /wp:image -->

<!-- wp:paragraph -->
<p>Use the block-moving tools to move the block up and down the editor. Use the six dots icon to drag and drop the {Block Name} block and reposition it anywhere on the editor. Alternatively, click on the up and down arrows to move the block up or down the editor.</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph {"style":{"color":{"background":"#e5f5fa"}}} -->
<p class="has-background" style="background-color:#e5f5fa">Get the details on&nbsp;<a href="https://wordpress.org/support/article/moving-blocks/">moving a block within the editor.</a></p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p><strong>Change</strong> <strong>Alignment</strong> </p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>The block toolbar for the <em>{block name} block</em> has options for alignment.</p>
<!-- /wp:paragraph -->

<!-- wp:image {"align":"center","id":15863328,"width":768,"height":398,"sizeSlug":"large","linkDestination":"media"} -->
<figure class="wp-block-image aligncenter size-large is-resized"><a href="https://wordpress.org/support/files/2019/03/Latest-Comments-HelpHub-SS-3.png"><img src="https://wordpress.org/support/files/2019/03/Latest-Comments-HelpHub-SS-3-1024x530.png" alt="Alignment controls for the latest comments block" class="wp-image-15863328" width="768" height="398"/></a><figcaption class="wp-element-caption">Alignment controls for the latest comments block</figcaption></figure>
<!-- /wp:image -->

<!-- wp:list -->
<ul><!-- wp:list-item -->
<li><strong>Align left</strong> - Make the block left-aligned.</li>
<!-- /wp:list-item -->

<!-- wp:list-item -->
<li><strong>Align center</strong> - Make the block alignment centered.</li>
<!-- /wp:list-item -->

<!-- wp:list-item -->
<li><strong>Align right </strong>- Make the block right-aligned.</li>
<!-- /wp:list-item -->

<!-- wp:list-item -->
<li><strong>Wide width</strong> - Increase the width of the block beyond the content size.</li>
<!-- /wp:list-item -->

<!-- wp:list-item -->
<li><strong>Full width</strong> - Extend the block to cover the full width of the screen.</li>
<!-- /wp:list-item --></ul>
<!-- /wp:list -->

<!-- wp:paragraph -->
<p>The "Wide width" and "Full width" alignment settings must be enabled by your WordPress theme.&nbsp;</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p><strong>More Options</strong> </p>
<!-- /wp:paragraph -->

<!-- wp:image {"align":"right","id":15878400,"width":255,"height":474,"sizeSlug":"full","linkDestination":"none"} -->
<figure class="wp-block-image alignright size-full is-resized"><img src="https://wordpress.org/support/files/2022/08/Screen-Shot-2022-08-01-at-10.22.26-AM.png" alt="More options in the latest comments block" class="wp-image-15878400" width="255" height="474"/></figure>
<!-- /wp:image -->

<!-- wp:paragraph -->
<p><strong>Hide Block Settings</strong></p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>The <em>Hide Block Settings </em>option hides (or shows) the Block Setting panel in the editor's sidebar.</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p><strong>Select parent block</strong></p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>The&nbsp;<em>Select parent block</em>&nbsp;lets you navigate to the parent block inside which the selected block is nested.</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p><strong>Copy</strong></p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p><em>Copy</em>&nbsp;can be used to copy a selected block and then you can paste it wherever you want in the editor.</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p><strong>Duplicate</strong></p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p><em>Duplicate</em> can be used to duplicate selected block.</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p><strong>Insert Before</strong></p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>Insert a new block before the selected block(s).</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p><strong>Insert After</strong></p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>Insert a new block after the selected block(s).</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p><strong>Lock</strong></p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>Since WordPress 6.0, you can lock the block to disallow moving and/or removing. If you lock the block, the “Lock” icon will be shown in the Block Toolbar.</p>
<!-- /wp:paragraph -->

<!-- wp:image {"id":15878414,"width":233,"height":172,"sizeSlug":"full","linkDestination":"none"} -->
<figure class="wp-block-image size-full is-resized"><img src="https://wordpress.org/support/files/2022/08/Screen-Shot-2022-08-01-at-10.30.04-AM.png" alt="Locking in the Latest Comments block." class="wp-image-15878414" width="233" height="172"/></figure>
<!-- /wp:image -->

<!-- wp:paragraph {"style":{"color":{"background":"#e5f5fa"}}} -->
<p class="has-background" style="background-color:#e5f5fa">For more details about Lock, refer to&nbsp;<a href="https://wordpress.org/support/article/more-options/">More Options</a>.</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p><strong>Add to Reusable blocks</strong></p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>Using the <em>Add to Reusable blocks</em> option lets you add the selected block to a list of reusable blocks, so you can use them on other posts or pages as well. </p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p><strong>Group</strong></p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>Select the <em>Group</em> option if you want to create a group of blocks and treat them as a unit. You can for instance add a common background color or other blocks to the group. </p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p><strong>Remove {Block Name}</strong></p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>With the <em>Remove {Block Name} </em>option<em>,</em> you can delete the selected block from your content. </p>
<!-- /wp:paragraph -->

<!-- wp:heading -->
<h2>Block Settings</h2>
<!-- /wp:heading -->

<!-- wp:paragraph -->
<p>Every block has specific options in the editor sidebar in addition to the options found in the block toolbar. <em>If you do not see the sidebar, simply click the 'cog' icon next to the Publish button.</em></p>
<!-- /wp:paragraph -->

<!-- wp:image {"align":"center","id":15863331,"width":377,"height":120,"sizeSlug":"full","linkDestination":"none"} -->
<figure class="wp-block-image aligncenter size-full is-resized"><img src="https://wordpress.org/support/files/2019/03/Latest-Comments-HelpHub-SS-4.png" alt="Enable block settings for the Latest Comments block" class="wp-image-15863331" width="377" height="120"/></figure>
<!-- /wp:image -->

<!-- wp:paragraph -->
<p><strong>{Block Name} Settings</strong> </p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>The {Block Name} Settings allow you to {describe the settings options here}.</p>
<!-- /wp:paragraph -->

<!-- wp:image {"align":"center","id":15863332,"width":356,"height":458,"sizeSlug":"full","linkDestination":"none"} -->
<figure class="wp-block-image aligncenter size-full is-resized"><img src="https://wordpress.org/support/files/2019/03/Latest-Comments-HelpHub-SS-5.png" alt="Block settings for the latest comments block" class="wp-image-15863332" width="356" height="458"/><figcaption class="wp-element-caption">Latest Comments Settings</figcaption></figure>
<!-- /wp:image -->

<!-- wp:paragraph -->
<p><strong>Advanced</strong></p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>The advanced tab lets you add a CSS class to your block, allowing you to write custom CSS and style the block as you see fit.<br></p>
<!-- /wp:paragraph -->

<!-- wp:image {"align":"center","id":15863334,"width":332,"height":163,"sizeSlug":"full","linkDestination":"media"} -->
<figure class="wp-block-image aligncenter size-full is-resized"><a href="https://wordpress.org/support/files/2019/03/Latest-Comments-HelpHub-SS-6.png"><img src="https://wordpress.org/support/files/2019/03/Latest-Comments-HelpHub-SS-6.png" alt="The advanced section lets you add a CSS class to your block." class="wp-image-15863334" width="332" height="163"/></a><figcaption class="wp-element-caption">The advanced section lets you add a CSS class to your block.</figcaption></figure>
<!-- /wp:image -->

<!-- wp:group {"backgroundColor":"very-light-gray","textColor":"very-dark-gray","className":"changelog"} -->
<div class="wp-block-group changelog has-very-dark-gray-color has-very-light-gray-background-color has-text-color has-background"><!-- wp:heading {"level":4} -->
<h4 id="changelog">Changelog<strong> </strong></h4>
<!-- /wp:heading -->

<!-- wp:list -->
<ul><!-- wp:list-item -->
<li>Updated 2022-08-01<!-- wp:list -->
<ul><!-- wp:list-item -->
<li>Added ALT tags for the images</li>
<!-- /wp:list-item -->

<!-- wp:list-item -->
<li>Updated {describe your update here}</li>
<!-- /wp:list-item --></ul>
<!-- /wp:list --></li>
<!-- /wp:list-item -->

<!-- wp:list-item -->
<li>Created 2019-03-07</li>
<!-- /wp:list-item --></ul>
<!-- /wp:list --></div>
<!-- /wp:group --></div>
<!-- /wp:group -->

[zzap]

I created pattern in https://wordpress.org/patterns/

It's pending review right now

[samxmunoz]

💃🏼 Yes! Go team! 🚀

[colorful-tones]

Update: @zzap made us aware that her pattern was not approved.

Based on my research today I've come to understand that the Meta team is currently working through the redesign process for many .org sites. HelpHub is one of these sites.

Based on this information, I've reached out in the #meta Slack for guidance on how we might create a block pattern. It may be a matter of waiting for a few weeks for the dust to settle for the Meta team, because I'm sure the redesign process is probably their main focus. We'll see. 🤞

[samxmunoz]

Awesome thanks for sharing an update here @colorful-tones! Appreciated.

[colorful-tones]

@zzap @samxmunoz I opened a new Trac ticket, as advised by the #meta team. https://meta.trac.wordpress.org/ticket/6556