/example-sage-theme

Modern theme development with WP Engine

Primary LanguagePHP

WP Engine Example Sage Theme

An example of how write beautiful and modern templates, with modern CI/CD practices using github actions and the Roots/Sage theme using wpengine.com

To produce beautiful themes like

<a class="sr-only focus:not-sr-only" href="#main">
  {{ __('Skip to content') }}
</a>

<div class="flex flex-col h-screen">
  <div>
    @include('sections.header')
  </div>

  <main id="main" class="w-full max-w-6xl px-4 mx-auto mt-6 mb-auto">
    @yield('content')
  </main>

  @include('sections.footer')
</div>

To get started

You can either clone and modify this repo as a starter or copy these steps to recreate a fresh install on your own.

Clone this repo

  1. First clone this repo with a sage theme
git clone https://github.com/wpengine/example-sage-theme <wordpress-dir>
cd <wordpress-dir>

  1. Setup a new ssh private key in GithHub and WP Engine via https://wpengine.com/support/github-action-deploy/#Setup_Instructions

  2. Add GitHub Action Secrets

Add the following secrets to your repo:

  • WPE_SSHG_KEY_PRIVATE: Your SSH private key.
  • THEME_NAME: The name of your WordPress theme in wp-content/themes/{theme-name}.
  • DEV_ENVIRONMENT: Your WPEngine site's development environment name (e.g., sitename-dev).
  • STG_ENVIRONMENT: Your WPEngine site's staging environment name (e.g., sitename-stg).
  • PROD_ENVIRONMENT: Your WPEngine site's production environment name (e.g., sitename).
  1. Push the repo to your own GitHub and the post-deploy.sh will activate the theme if it's not already, and clear the cache during GitHub deploys 🎉.

Frequently Asked Questions

  • I thought WP Engine doesn't support Sage/Roots theme?
    • Sage was never fully supported due to the way Sage out of the box conflicted with our security best practices. In late 2022, we started to make changes to fully support pre-compiling Sage templates to enable official support if they follow the way this repo deploys with post-deploy.sh script, that ultimately runs wp acorn view:cache.
  • Sage wasn't supported until late 2022?
    • There have been ways of running Sage on WP Engine prior using customization or other means, but this approach is our offically supported way.
  • What about Timber/Twig themes?
    • Those themes are also supported! Just disable filesystem caching and let our other, more advanced, caching mechanisms take the place of that.
  • Why not just disable filesystem caching on Sage the same way?
    • That's probably another great alternative, but it requires more effort/customization then many of our customers want, if that is a route you want to go, please be sure to let our support team know when you've made progress there and we'd love to add docs on how to accomplish that as well!
  • I have more questions or need more help!

Alternatives

Also check out local, our effortless way to develop WordPress sites locally. Just be sure to run

wp acorn view:cache

after pushing changes to wpengine.com.