Block Theme Support Page

[annezazu]

Needed for 5.9 and needs to include the following:

• How to find block themes.
• What block themes are.
• What options are available with block themes (Styles, Templates, Template Parts).
• How to update site icon: https://core.trac.wordpress.org/ticket/54370
• How to update what your homepage shows
• Template overviews.
• Template part overviews.

[carolinan]

Public preview of the draft: https://wordpress.org/support/?p=15113575&post_type=helphub_article&preview=1&_ppp=7b721b13e7

[annezazu]

Sent feedback to you via DM. Thanks so much for kicking this off!

[annezazu]

@carolinan do you still think this is something you can see to completion? I have a lot of time dedicated before the end of the year so was thinking of going through and finalizing this one but wanted to check in first :)

[carolinan]

@annezazu You can finalize it if you want.
I was waiting to see if there was any progress on the site icon. It doesn't look like the site icon features are going to be in 5.9 so I think that part needs to be removed.

[annezazu]

Oh my gosh! Amazing timing - I was watching this PR as I do think this is going to make it into 5.9 (listed as backport) WordPress/gutenberg#35892 (comment) and was going to start a doc for the Site Logo block: #88 Thinking more though, that's definitely overkill and it would be better to mention within your doc itself :)

[carolinan]

I did not see that it got merged :)

[annezazu]

Went through to update as much as I could but am confused by the Static Page section. Mind finishing that part @carolinan ? For example, with TT2 there isn't a homepage template to set with a page or post. From my vantage point, the main way to set a static page would be to select a static page option in Settings > Reading to then edit in the Editor. Otherwise, if I create a new Front Page template in the site editor, I don't see a way to assign it to a page.

For the site icon option, I wrote out a section thinking the site icon option would work but found it wasn't in beta 4: WordPress/gutenberg#37677 TLDR seems like it might make it into a point release but not likely for 5.9. Copying what I wrote here for when it might be ready in the future:

<!-- wp:heading -->
<h2 id="how-to-update-your-site-icon">How to update your site icon</h2>
<!-- /wp:heading -->

<!-- wp:paragraph -->
<p>Block themes include the ability to use the Site Logo block which has built within it an option to set your Site Logo as your Site Icon. For context, the Site Logo simply displays whatever logo you set for your site whereas your Site Icon is also known as a favicon and it is used to help identify your website. To learn more about setting your Site Icon or favicon, please see the support article <a href="https://wordpress.org/support/article/creating-a-favicon/">Creating a Favicon</a>.</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>Follow the steps below to use the same image for the Site Logo and Site Icon:</p>
<!-- /wp:paragraph -->

<!-- wp:list {"ordered":true} -->
<ol><li>Head to Appearance > Editor (beta). This will open up your homepage. </li><li>Either find your Site Logo block added by your theme or add it to yourself wherever you'd like. Detailed instructions for adding blocks <a href="https://wordpress.org/support/article/adding-a-new-block/">can be found here</a>. </li><li>From there, you'll see the option to upload or select an image to use from your Media Library. </li><li>After choosing an image and while still selecting the Site Logo block, open the block settings sidebar (uses the cog icon). </li><li>Under the settings for the Site Logo block, toggle on the option to "Use as site icon". </li><li>Save your changes.</li></ol>
<!-- /wp:list -->

Final note -- I am working on the site editor doc next week #93 and have a feeling that both the setting homepage displays + site icon might belong better there so that could become another part of this page in particular that links to another (similar to how Templates and Template parts are discussed in this doc) . Do you have any preference or thoughts there?

[annezazu]

Because having visuals helps me... here's a very rough draft for the Site Editor, reusing pieces from this current doc: https://wordpress.org/support/?p=15201243&post_type=helphub_article&preview=1&_ppp=7b31478236

I personally think the following makes the most sense:

• Simplify the Block theme article even more when mentioning templates, template parts, styling. Perhaps just make this a bullet list :)
• Add more of the content to the Site Editor doc to build that out as the primary source.

This would make the Block Theme doc more about what block themes are + how to find and activate block themes + features built in rather than going in deep about the features. This would also make the Site Editor doc far more comprehensive in a way that pulls together the various features.

[mkaz]

I think you're on the right track, from a user point of view, the Site Editor is the key interface into the theme, so it makes more sense for the documentation to reflect that. The Block theme support page can focus more on theme basics like:

• what are difference between block/classic themes,
• explain things like "just because a theme shows an example color" you don't need to switch themes to change it you can update in the site editor (link to editor),
• what to look for when picking a block theme,

👍

[annezazu]

Awesome. Thank you for the confidence check! Glad my thinking isn't too far out there 🤠.

[carolinan]

I agree, the details you mentioned can be moved to the site editor help page.

[carolinan]

The previous preview link for the block theme support page expired, here is a new link:
https://wordpress.org/support/?p=15113575&post_type=helphub_article&preview=1&_ppp=8fd0686e9c

[carolinan]

I removed the part about how to update what your homepage displays. (See post revisions or below for a backup).
I also added a heading above the paragraph about the widgets, and updated the images.

I find this paragraph difficult to read, can we split the first sentence into two shorter ones?

"A Template part is a block for managing different areas of your webpage that help set structure for reusable items like a Footer or Header that one typically sees in a WordPress site. They are primarily meant to be used for site structure. "

---

Expand

How to update what your homepage displays

Your homepage can show a list of your latest blog posts or a static page with custom content. To set what you want to appear, head to Administration Screen > Settings > Reading. To learn how to select a page for your homepage, please see the support article Creating a Static Front Page.

How to customize your homepage

Latest Blog Posts

To customize your blog, go to Administration Screen > Appearance > Editor (beta). The editor will open to your homepage, and you can start editing.

Block themes display lists of blog posts with the Query Loop block and the Post Template block.
The support article for the Query Loop Block explains how to configure the block.

When you add a block inside the post template block, it is repeated for every post in the list. The Post Title and Post Featured Image, Post Author, Post Date, Post Category, and Post tags are examples of blocks that you can use to customize your blog.

Static page

If you want your homepage to have a different design than other pages, you need to assign it a template. If your theme does not include a homepage template, you can create a new template.

Follow these steps to assign an existing template:

1. Open your selected page in the editor.
2. Open the page settings sidebar:
   [image]
3. In the Template panel, select the homepage template in the list.
   [image]
4. Optionally, you can preview your page.
5. Save.

Follow these steps to create a new template:

1. Open your selected page in the editor.
2. Open the page settings sidebar:
   [image]
3. In the Template panel, select New.
   [image]
4. Next, select a name for your template.
   [image]

You are now in the template editor and you can customize the blocks that show on the homepage. When you have made your changes, save the template and the page.

[hellofromtonya]

With 5.9 RC1 today, need to get a link to the new support page for the block themes. The Welcome Panel has a link to it, which is https://wordpress.org/support/article/block-themes/, a guess of what the article's URL might be. Is this the right URL? Or ___?

[annezazu]

Yes. The link will be this: https://wordpress.org/support/article/block-themes/.

[annezazu]

@carolinan can you check out this preview? https://wordpress.org/support/?p=15113575&post_type=helphub_article&preview=1&_ppp=8fd0686e9c

I moved the big pieces to the Site Editor doc and then listed key features as as bullet items with links to each individual doc. I also added in more notes around how you can customize key parts of your theme without needing to necessarily switch. It makes for a more contained and focused doc that I think works well but definitely would love thoughts!

[carolinan]

"With a block theme, you can place and edit blocks outside your content using the Template Editor or by going to the Administration Screen > Appearance > Editor (beta). "

I think this can be shortened now that we can use the term "site editor", and it should link to the new page.

[carolinan]

In the list below "What options are available with block themes?" could we switch places of template parts and templates? Because templates are required and template parts are optional.
Maybe add a link to the navigation block page?

One concern that I have is that when we compare classic themes and block themes, this might only make sense for users who have used classic themes and are already familiar with terms like widgets and the customizer, and not users who are new to WordPress.

I think that as a new user, it maybe difficult to know what type of theme to select, a classic theme or a block theme?

[annezazu]

Thank you -- updated the following considering your feedback:

• Updated to mention how this is coming to 5.9
• Updated to just say Site Editor in the section you flagged.
• Changed order of templates and template parts.
• Added in a brief "When should I use a block theme?" section (can evolve this)
• Added link to navigation block page and query loop under "How are block themes different from classic themes?" while mentioning theme blocks.

Going to ship today in light of this convo in slack where current links in 5.9 RC1 are broken because these are not published.