WordPress starter theme with Laravel Blade components and templates, Tailwind CSS, and a modern development workflow

Website    Documentation    Releases    Support

Supporting

Sage is an open source project and completely free to use.

However, the amount of effort needed to maintain and develop new features and products within the Roots ecosystem is not sustainable without proper financial backing. If you have the capability, please consider donating using the links below:

Features

• Harness the power of Laravel and its available packages thanks to Acorn.
• Clean, efficient theme templating utilizing Laravel Blade.
• Lightning fast frontend development workflow powered by Bud.
• Out of the box support for Tailwind CSS.

Requirements

Make sure all dependencies have been installed before moving on:

• WordPress >= 5.9
• PHP >= 7.4.0 (with php-mbstring enabled)
• Composer
• Node.js >= 16
• Yarn

Acorn

Although Sage makes use of Acorn, it doesn't ship with it included. This is to give you the flexibility to include it in a way that works best for your environment.

• Bedrock is the recommended way to manage your WordPress installation, themes, and plugins. If you're using Bedrock, you only need to require Acorn as a composer dependency in your Bedrock composer.json:

  $ composer require roots/acorn

• If Bedrock isn't feasible, then the next best approach is to install Acorn as an mu-plugin. This guarantees that it will always be available and someone won't accidentally disable it and break your site. Add the Acorn directory to your mu-plugins directory, and make sure you have something to load it automatically, like our bedrock-autoloader.
• If neither of the preceding options is workable for you, then Acorn can always be installed as a normal plugin by putting the Acorn directory in your plugins folder. Just remember to activate it!

Theme installation

The main branch currently tracks Sage 10 which is in active development. Looking for Sage 9 or the latest Sage 10 beta release? See releases.

Install Sage using Composer from your WordPress themes directory (replace your-theme-name below with the name of your theme):

# @ app/themes/ or wp-content/themes/
$ composer create-project roots/sage your-theme-name

To install the latest development version of Sage, add dev-main to the end of the command:

$ composer create-project roots/sage your-theme-name dev-main

Make sure that you have Acorn installed. See the "Acorn" section above for instructions.

Theme structure

themes/your-theme-name/   # → Root of your Sage based theme
├── app/                  # → Theme PHP
│   ├── Providers/        # → Service providers
│   ├── View/             # → View models
│   ├── filters.php       # → Theme filters
│   └── setup.php         # → Theme setup
├── composer.json         # → Autoloading for `app/` files
├── public/               # → Built theme assets (never edit)
├── functions.php         # → Theme bootloader
├── index.php             # → Theme template wrapper
├── node_modules/         # → Node.js packages (never edit)
├── package.json          # → Node.js dependencies and scripts
├── resources/            # → Theme assets and templates
│   ├── fonts/            # → Theme fonts
│   ├── images/           # → Theme images
│   ├── scripts/          # → Theme javascript
│   ├── styles/           # → Theme stylesheets
│   └── views/            # → Theme templates
│       ├── components/   # → Component templates
│       ├── forms/        # → Form templates
│       ├── layouts/      # → Base templates
│       ├── partials/     # → Partial templates
        └── sections/     # → Section templates
├── screenshot.png        # → Theme screenshot for WP admin
├── style.css             # → Theme meta information
├── vendor/               # → Composer packages (never edit)
└── bud.config.js         # → Bud configuration

Theme setup

Edit app/setup.php to enable or disable theme features, setup navigation menus, post thumbnail sizes, and sidebars.

Theme development

• Run yarn from the theme directory to install dependencies
• Update bud.config.js with your local dev URL

Build commands

• yarn dev — Compile assets when file changes are made, start Browsersync session
• yarn build — Compile assets for production

Sage sponsors

Help support our open-source development efforts by becoming a GitHub sponsor or patron.

Community

Keep track of development and community news.

• Join us on Roots Slack by becoming a GitHub sponsor or patron
• Participate on the Roots Discourse
• Follow @rootswp on Twitter
• Read and subscribe to the Roots Blog
• Subscribe to the Roots Newsletter