How to switch to a block theme guide

[annezazu]

What is the new page you are requesting?

With Learn WP holding workshops on migrating to a block theme and with 6.2 removing the beta label for the Site Editor, it seems wise to have some general resources around how best to migrate, ways to make it easier, common mistakes, etc. This came up when chatting with the folks who ran the Learn WP session to see what feedback they might have!

I can imagine it being similar to @carolinan lovely work here: https://fullsiteediting.com/site-creators/switch-your-website-to-full-site-editing/#h-how-to-decide-if-you-should-switch-to-full-site-editing Noting this to ensure we can learn from broader community resources and to see what @carolinan thinks of how best to approach this from a Core documentation stand point.

[zzap]

Heads up @WordPress/docs-issues-coordinators, we have a new issue open. Time to use 'em labels.

[wparasae]

People are largely excited about making the switch to a block theme, saying things like: "Block themes seem to provide for more flexibility in translating my vision into reality" "Block themes are the future of WP. Give more control to us." "Just wanna get rid of [classic] themes out there. They are almost always slow" "I find it easier to use."

Pain Points:

1. People are confused about what permissions different user roles have and what different roles can/cannot do in the site editor.

2. Thinking like a long-time intermediate user switching from a classic theme to a block theme, I could see some confusion about what is content and what is theme. Site Editing makes it a lot easier to accidentally write your content in the wrong spot.

3. One point of confusion from a user: "It seems like block themes are not yet ready for custom post types/custom fields, displaying meta data."

[github-actions[bot]]

Heads up @femkreations @atachibana - the "user documentation" label was applied to this issue.

[github-actions[bot]]

Heads up @zzap @femkreations - the "block editor" label was applied to this issue.

[carolinan]

The article linked above is a bit of a beast - If I was a user and I saw that I had to go through all those manual steps, I would probably put it off as long as I could. 😵‍💫

I wonder if user permission for the site editor (or blocks) should be a separate support article, if there isn't one already?

Needs input from real users who has switched. Maybe additional pain points can be found in the Twenty Twenty Three and Twenty Twenty Two support forums. @kathrynwp

I think the customizer, widgets, the navigation menu screen and their replacements must be included. I will watch the workshop, and after that maybe we can start with an outline.

[zzap]

Is this something that is actively being worked on?

[carolinan]

I have not forgotten about this article. It has been difficult to get started. I don't have a lot of contact with users who are switching.

Regarding the pain points above:

1) User permissions - think this should be part of https://wordpress.org/documentation/article/roles-and-capabilities/ and referenced from "how to switch"

3) Meta fields is an advanced topic, and also one that is not solved in WordPress with and without Gutenberg. (Notable: A classic theme also do not display meta data without a developer adding additional code)

[carolinan]

Resources: https://wordpress.tv/2023/06/01/how-to-switch-from-a-classic-to-a-block-theme/ https://wordpress.tv/2023/02/23/how-to-confidently-migrate-from-a-classic-theme-to-a-block-theme/

[carolinan]

I think why and when and when not to should be excluded since these are more opinionated than how ? What do you think?

What do you think about this outline. Is it too basic?

What is a block theme?

First, reference "What is a block theme" and "how to find a block theme" https://wordpress.org/documentation/article/block-themes/ in case visitors land on the "how to switch" guide and are unsure.

Before you switch, create a backup

Secondly, remind the reader to work on a test site or create a backup of their site https://wordpress.org/documentation/article/wordpress-backups/

Test your plugins

As a third step, think the guide should recommend the user to make a list of the plugins they still need, and test that the plugins work with the block editor and site editor. -Check if a plugin can be replaced with an existing block or editing feature, and remove that plugin if it is no longer needed. -Check that the plugin features still work. -Include a paragraph or two about what the user should do if the plugin does not work: https://wordpress.org/documentation/article/faq-troubleshooting/

How to update the front page

First, the reader should choose if the front page of their website should show the blog or page content.

Explain how to setup the reading settings. Reference: https://wordpress.org/documentation/article/create-a-static-front-page/

Next explain how to select and edit the front page. Reference: https://wordpress.org/documentation/article/site-editor/ https://learn.wordpress.org/tutorial/creating-a-front-page-for-a-block-theme/ https://learn.wordpress.org/tutorial/creating-a-landing-page-with-a-block-theme/

How to change what is shown on the blog:

Explain how to edit blocks inside the post template block inside the query: Hiding/removing/adding featured image block, tags, post date.

How to update the site header

First, include how to access and edit the template part. Reference https://wordpress.org/documentation/article/template-part-block/

Explain how to update the site title, site tagline and site logo blocks.

https://learn.wordpress.org/tutorial/creating-a-new-header-with-blocks/

Next, explain how to import the previous menu, their classic menu, in the navigation block. Reference https://wordpress.org/documentation/article/navigation-block/#selecting-an-existing-menu

How to update the site footer

Here, explain how to import classic widgets as part of the site footer. https://learn.wordpress.org/tutorial/importing-widget-areas-from-a-classic-theme-to-a-block-theme/

Advanced editing

Encourage the reader by giving them some examples of what is possible to customize: Site Editor > Styles Updating the 404 page

Adding sidebars https://learn.wordpress.org/tutorial/building-sidebars-with-the-site-editor/

Custom templates https://learn.wordpress.org/tutorial/creating-a-custom-template-with-the-wordpress-site-editor/

[annezazu]

Thanks for starting this outline! Excellent. I agree on removing why and when and when not. We should be careful to try to guide folks there. The only thing missing right now that I think is worth including is the ability to preview block themes coming to 6.3. I think that's worth calling out to help encourage folks to try previewing and using the Site Editor before switching. It could help surface issues with the site and gives folks a space to make fixes before moving on.

[carolinan]

I though about the preview. I think that probably belongs on https://wordpress.org/documentation/article/work-with-themes/#adding-block-themes

[annezazu]

Hmm, makes sense. I could still see a brief mention of it though in this guide, even if we do link off.

[carolinan]

I have created a draft article here. So far, I have only added the headings. Everyone is welcome to edit it. I wasn't sure what categories to use, I added Customization > Appearance. https://wordpress.org/documentation/wp-admin/post.php?post=16358082&action=edit

[annezazu]

Some quick feedback and a note about adding in some content from Learn to resources:

Some older plugins are not built to work with block themes.

Changed to: "Some plugins are not built..." I worry about just saying "older" as this could apply to any plugin.

For "Test your plugins", should we include the option of creating a test site?

You can start by copying media files and uploading them to your Media Library. Then copy your text content into a seperate text file for backup.

Why would folks copy the media files?

@jordesign this would be a high impact doc to help with ✨ Let's make sure it's consistent with what's here: https://learn.wordpress.org/tutorial/how-to-switch-from-a-classic-to-a-block-theme/ @wparasae perhaps we can reuse some of what you have in that tutorial to speed this up!

[carolinan]

Why would folks copy the media files?

I meant that many themes especially commercial themes have media files in the theme folder, remotely, or in a companion plugin. So if the user wants to keep them they need to upload them to the media library.

[jordesign]

Thanks Anne - great suggestion - I'll put it on my backlog/todo to review and see about helping out :)

[github-actions[bot]]

Heads up @docs-reviewers - the "[Status] Review" label was applied to this issue.