WordPress.org
Get WordPress
WordPress.org

WordPress Developer Resources

Theme Structure

Theme Structure

In this article

  • Files and folders
    • Advanced theme structure

    Back to top

    In the Getting Started chapter, you learned the basics of what a theme is and how to get one up and running without code. A no-code approach is perfectly OK for simple themes, but once you want to add things that are not possible in the user interface, you’ll need to start working directly with code.

    The first step of customizing theme code is to open the theme in your preferred file editor. You can use any theme for this, even the one you created from the Getting Started chapter.

    It’s a good idea to familiarize yourself with what others are doing, so feel free to look at several block themes from the WordPress theme directory.

    This document will walk you through what the file and folder structure will look like in a typical block theme.

    Files and folders

    WordPress themes are nothing more than a collection of various files that rely on different web technologies, such as HTML, CSS, and PHP. Block themes also follow a standard structure in how many of those files are laid out.

    At its most basic, a theme’s structure will look similar to the following. Take note of the files/folders marked required because they are necessary for a block theme to work:

    Required files

    There are two necessary files for WordPress to recognize your block theme, and you will learn more about these in the coming documentation:

    Optional files

    A theme can include any number of custom files other than the required list above. WordPress also looks for a few other files and uses them if they are available:

    Standard folders

    In the example above, there were a few folders included. A theme can have many more folders, but WordPress has designated a few of them for specific features. You will learn more about these folders as you read through this chapter:

    Advanced theme structure

    This section is meant to familiarize you with some of the common files you’ll see in themes but not to cover every possibility in detail. These files are entirely optional and will differ from theme to theme. You may skip this section for now if you are not comfortable with more advanced development methods.

    In reality, block themes can contain many more files and folders. The more complex the project becomes, the more complex its structure will be. 

    Let’s add a few extra files and folders to the original example:

    Optional folders

    There is no limit on what folders may be included, but the above example added two of the most common use cases you’ll come across in WordPress themes:

    Optional files

    This list is nowhere near exhaustive, but it includes some common files used in theme development. (Note: most of the following links lead to external, third-party sites and are not affiliated with WordPress.)

    Don’t feel discouraged if you do not understand all of these files and their purposes yet. Again, these are entirely optional elements of a developer’s workflow. Feel free to learn more about them at your own pace at a later time.

    Code editor view

    Here is a quick editor view of a real-world theme with an advanced structure:

    Visual Studio Code editor showing the structure of a theme's files and folders. In the code area, a theme.json file is shown.

    This is vastly more complex than the basics that this documentation is introducing. The point is that, even when building block themes following standard practices, you will have a lot of freedom to customize things. You may want to integrate with version control systems, add in a build process, and more.

    So, consider this documentation the foundation in which you can build upon. But there is no harm in keeping it simple and sticking with the basics.

    First published

    Last updated