Introduction to block theme development (for beginners)

Learn the basics of building the simplest functional block theme possible from scratch using a text editor and local development environment.

Learning outcomes

  1. Create your first basic empty block theme of your very own
  2. Briefly explain what each necessary file does in a block theme

Comprehension questions

  1. What two tools do you need in order to create your first blank block theme?
  2. What are the two files needed for WordPress to show your WordPress website in your WordPress dashboard?
  3. What folder and file are needed to transform your theme into a block theme?


If you’re new to theme development like me, you might find it hard to picture the steps it takes to go from no theme at all to your very first blank custom block theme. The WordPress developer handbook explains it well, but what does this look like in action? This brief tutorial is meant to help demystify what essential files you need, and how to set them up to go from zero theme to a brand new totally blank block theme. And as you’ll discover, it’s easier to get the very basic setup than you might expect. By the end of this video, you will be able to create your first basic empty block theme of your very own and briefly explain what each necessary file does. To get started, you will need a few things. One, a local development environment such as Local, XAMPP,

or MAMP, and to a text editor, such as Visual Studio Code, Sublime, or PHP storm.

Finally, you’ll need to set up a sample WordPress website to experiment with and create your files. Once you have these things, you’re ready to go. Let me walk you through it. I will be using Local by Flywheel today and Visual Studio Code. First, I will make my sample WordPress website. This gives me a place to experiment. Once that is setup, I will navigate into the Local files where WordPress themes live.

Please note that it can be a little tricky to find Local’s WordPress files the first time so I made a shortcut to them here for my own computer. Be aware that you may need to do some digging in your computer to find your development environment’s WordPress files.

Now, I’m going to open up my text editor.

Once I found my sample websites WordPress files, I will navigate to its “themes” folder. I click the name of my sample site and click app then public. Then, I scroll down to WP-content.

From there, I select “themes” and I’m there.

Here I will create a new folder where my brand new themes files will live. I’m going to call this new block theme, “My Dream Theme”. So that is what I will name this folder.

You will see that it’s empty inside.

It’s time to create its first files. I will start creating my new blog theme with the first of the three files index dot PHP. I don’t need to write very much here. All you’ll see me type is left caret question mark PHP, no other coding at all. This file was once an all important file for classic themes, but now exists largely as a safety feature to prevent hackers from being able to see a full list of your themes and our files. In the future, this file may no longer be needed at all. But as of August 2022, it’s necessary for block themes to function securely.

Before you’ll find your theme in your WordPress dashboard, you need a second file style.css. This files purpose is to tell WordPress itself, “Hi, WordPress I exist.” I’ll include some code here slash star on the first line. And on the second line, I’ll type theme name: My Dream Theme. The third line, I’ll write Author: Sarah Snow.

And on the last line, I’ll write star slash to finish it up. This file alerts WordPress that my theme exists and WordPress responds by showing my theme in my WordPress dashboard. Congratulations, your theme exists and can even be activated.

If you click around, you’re going to find that your custom theme might exist, but it doesn’t do much of anything yet. Where’s the Block Editor? How does this newborn theme grow into an actual full block theme?

Once that folder is created, create a new file index.html. Make sure this index.html file is inside the Templates folder or it won’t work. You don’t even need to add code to this file to watch your theme transform into a beautiful new block theme. Watch as I reload my dashboard. Suddenly I can use the site editor. Congratulations you now

Take a look at how the template folder you just made and the empty index.html file you created show up in the site editor. Cool, right?

Please note that this is just the first step in creating a custom block theme. There’s still quite a bit more to learn. For example, if you make changes in the site editor, you have to export your theme in order for these changes to be written to these files that you just created. There’s also a world of new possibilities with theme.json code. Visit in the future for new tutorials and courses to discover the next steps to build a custom block theme of your very own. Of course, you can always head to the theme handbook at We’ll see you next time.

We need one more directory and one more file to make it happen.

First, this new file needs a folder to live in. We will name this new folder templates with an S at the end. You use your text editor to create this new folder.

Workshop Details


Sarah Snow

WordPress educator and/or mad scientist; my professional hobbies include breaking WordPress websites in front of audiences, investigating simple solutions to odd problems collaboratively, and designing lesson plans and courses for Ask me about caring for parrots, training stubborn Shar Peis, cooking super spicy recipes, learning American Sign Language & French, teaching and writing. Changing the narrative one story at a time.