An Introduction To The Sage WordPress Starter Theme

WordPress is an awesome and powerful tool. It's not without reason that more than a third of all websites are powered by it. Unfortunately, its development workflow feels quite outdated and clunky when compared to PHP Laravel and many front-end frameworks. This can be mainly attributed to the core development team striving to never break backwards compatibility. 🙄 Fortunately, a group of talented developers, working under the company name of Roots, have taken it upon themselves to make WordPress development much more modern and streamlined. In this article, I'll be giving you an introduction to the Sage WordPress starter theme, their most popular project.

I'll be discussing what Sage has to offer, how to install it and how to read its folder structure.

What Sage offers

If you're coming from a more traditional web development background, you'll be familiar with some of the tools Sage offers.

First, Sage is based on Webpack. For those of you who are unaware of what it its: it's a module blunder. In layman's terms, it's a front-end tool that takes your interdependent assets (e.g. JavaScript, images, HTML, CSS, …) and processes it into something usable by the client aka website visitor. 🧍‍♂️ This might involve processing Sass, checking JavaScript for errors, optimizing images, etc. But honestly, you rarely ever need to mess with Webpack, so it's something you may safely ignore for the time being.

Second, it comes preconfigured with Bootstrap, the most popular UI framework, making web design much easier for us grouchy developers. However, if Bootstrap isn't your jam, you can easily configure it with other frameworks such as Bulma, Foundation, etc. Or for the daring among us, you may not use one at all! 😱

Last but not least, Sage uses PHP Laravel's templating engine Blade for DRY (Don't Repeat Yourself) code. Now, while WordPress does provide DRY templating to a certain extent, I believe Blade's focus on creating more maintainable projects just make it a better option over its vanilla counterpart.

An example of the templating language can be seen below.

@extends('layouts.base')

@section('content')
  @while(have_posts())
    {!! the_post() !!}
    @include('partials/content-single')
  @endwhile
@endsection

Installation

Before you can install the Sage starter theme, you first need to make sure you meet the following dependencies in your development environment:

• WordPress >= 4.7
• PHP >= 7.1.3 (with php-mbstring enabled)
• Composer
• Node.js >= 8.0.0
• Yarn

My preferred WordPress development environment uses Laragon, which comes with all these dependencies installed automatically. 😎 You may take a look at an article I wrote if you're interested in learning more about it!

Ahem, alright.... moving on. In your terminal, head over to the wp-contentthemes directory of your WordPress site. Then, execute the following command, replacing <your-theme-name> with a name of your choosing.

$ composer create-project roots/sage <your-theme-name>

Following this, Sage will be installed and you'll be prompted to answer several statements.

Regarding the prompt Path to theme directory (e.g., /wp-content/themes/tutorial) [/app/themes/sage], make sure to enter the path of your new theme, i.e. /wp-content/themes/<your-theme-name>. By default, it will suggest a different path that is used with one of Roots' other projects, namely Bedrock.

Last but not least, in your new theme folder, run yarn or npm install to install all the dependencies of your theme. Et voilà, the installation is complete! 💃

Aannndd don't forget, to run your site, type yarn start or npm run start.

TTY mode is not supported on Windows platform

For my fellow developers who are on Windows like I am, you'll likely encounter an error during the installation process: TTY mode is not supported on Windows platform. As a result, you won't be prompted any questions. However, if that's not the case for you, awesome! One less thing to worry about. 😀

To solve this problem, cd into your newly generated theme and simply run the following commands one by one:

$ vendorbinsage meta
$ vendorbinsage config
$ vendorbinsage preset

Folder Overview

Using any new tool can be daunting at first, 😥 which is why this section is dedicated to giving you an overview of Sage's project structure. To make this as digestible as possible, I'll go through each group of files one by one. And to make things more visually appealing, I'll be using the theme structure diagram from Roots' website.

App

├── app/                  # → Theme PHP
│   ├── controllers/      # → Controller files
│   ├── admin.php         # → Theme customizer setup
│   ├── filters.php       # → Theme filters
│   ├── helpers.php       # → Helper functions
│   └── setup.php         # → Theme setup

You can consider the app/ directory as the PHP logic 👩‍💻 of your site. controllers/ contains your controllers... duh! But seriously, this is where your PHP logic belongs, e.g. sending a confirmation email after a visitor signs up for a newsletter. Now, the other files you can consider as a split up functions.php file. Instead of having all your code in one place, they are grouped separately instead. 👨‍👩‍👧‍👦

You'll find yourself visiting this folder once in a while.

Config

├── config/

The name is pretty self-explanatory. This folder takes care of your theme's configuration, e.g. namespacing or the path to your assets. Frankly, you'll rarely ever touch this folder.

Resources

├── resources/            # → Theme assets and templates
│   ├── assets/           # → Front-end assets
│   │   ├── config.json   # → Settings for compiled assets
│   │   ├── build/        # → Webpack and ESLint config
│   │   ├── fonts/        # → Theme fonts
│   │   ├── images/       # → Theme images
│   │   ├── scripts/      # → Theme JS
│   │   └── styles/       # → Theme stylesheets
│   ├── functions.php     # → Composer autoloader, theme includes
│   ├── index.php         # → Never manually edit
│   ├── screenshot.png    # → Theme screenshot for WP admin
│   ├── style.css         # → Theme meta information
│   └── views/            # → Theme templates
│       ├── layouts/      # → Base templates
│       └── partials/     # → Partial templates

Without a doubt, this is where you'll be spending most of your time. 🕐 The resources/ directory contains all your PHP pages, JavaScript, HTML, etc of your site.

First of all, the assets/ folder contains your images, fonts, JavaScript and CSS/SCSS files. The folder build/ you shouldn't touch at all and config.json/ can be safely ignored as you almost never need to edit it. On the other hand, you'll find yourself working in the scripts/ and styles/ folder quite often.

Next, views/ contains all your PHP view templates, or to be specific the Laravel Blade template files that Sage uses. As a result, you'll see your files ending with blade.php. It is common practice to use layouts and partials in Blade template development, hence the folders. The latter is similar to WordPress partials, too.

Apart from these two folders, there are a bunch of other files which you can safely ignore as well. Lot of ignoring, right? Well, you might want to change the screenshot.png image, so your WordPress theme has a nice cover. 📷

Miscellaneous

├── composer.json         # → Autoloading for `app/` files
├── composer.lock         # → Composer lock file (never edit)
├── dist/                 # → Built theme assets (never edit)
├── node_modules/         # → Node.js packages (never edit)
├── package.json          # → Node.js dependencies and scripts
└── vendor/               # → Composer packages (never edit)

Lastly, I would call this the What? group, because that's the only thing you need to know about them. And by that I mean know nothing. 👉 Insert obligatory "You know nothing Jon Snow" joke here...

If you ever do need to edit the composer.json and package.json files, there are plenty of tutorials out there on how to do so. These files aren't specific to the Sage starter theme and hence I won't go into them.