Starting a new project


Get your new Wheat + Grav CMS project up and running on a local environment.

Before we begin

This guide is aimed at users wanting to start a brand new website project using Grav CMS and Wheat as starter kit. It will hopefully help you up to the point where you have a working website running a renamed version of Wheat on a local environment.

  • A PC running Windows (but I'm sure you can figure it out on Apple as well.)
  • A GitHub account
  • A cool project name
  • Internet
  • Access to Window's Command Prompt
  • XAMPP or something similar

Getting started

  • On GitHub, create a new repo named grav-theme-mytheme (where mytheme is your project name). (The grav-theme- prefix is not required but is good practice in Grav development. It is also required if you plan on releasing on the GPM). You wont need GitHub for a bit so you can close it once the repository has been created.

  • On your computer, create a folder named after your project.

  • Download the latest version of GRAV Core + ADMIN.

  • Unzip the downloaded Grav archive and put it in you project folder.

  • From inside grav-admin, cut the user folder and paste it right next to grav-admin.

  • At that point, your project folder should look like this:

  • Clone your theme repo in the project folder, next to the other ones so it looks like...
  • Delete the content of grav-theme-mytheme, if there is any.
  • Download Wheat latest release source code (zip) OR the evergreen Master branch.
  • Unzip the downloaded grav-theme-wheat-vx.x.x.
  • Dump the entire content of grav-theme-wheat-vx.x.x in your grav-theme-mytheme folder.

Cleaning and renaming

Alright so Wheat is now alive and well in your GitHub repo. It's now time to make it unique so we'll rename and clean a bunch of files. As a side effect, this will ensure I don't push unwanted updates on your theme trough the GPM if I publish Wheat on it.

  • wheat.yaml should be mytheme.yaml
  • wheat.php file name and any reference to the theme inside the PHP code (make sure you follow capitalization).
  • Erase the content of and start fresh with version v0.1.0 (or whatever you think is best).
  • Replace references to Wheat in blueprints.yaml and add your own informations.
  • Delete the content of _ROOT except serviceworker.js.
  • Adjust _ROOT/serviceworker.js CACHE variable name using your theme name and version.
  • Replace screenshot.jpg and thumbnai.jpg with your own images while following the size and format of the ones provided.
  • Commit to master. (congratulation! That's v0.1.0 of your new project.)
  • Create a new branch named develop and publish it.
  • From here on out, commit all changes to the new develop branch.


Since our 3 main folder (admin, theme and user) are side by side in our project folder, and probably not in our XAMPP web root, we need to symlink everything together. You'll have to change the paths bellow to fit with your setup. I usually keep a copy of this the _SETUP folder in the theme repo so I can get back on my feet quickly if anything happen.

Local webroot to Grav install

mklink /D D:\xampp\htdocs\myproject D:\myproject\grav-admin

grav-admin to user

mklink /D D:\myproject\grav-admin\user D:\myproject\user

user to theme

mklink /D D:\myproject\user\themes\mytheme D:\myproject\grav-theme-mytheme

Test your setup using your favorite browser and going to your local webroot (something like If everything goes well, Grav will prompt you to create an account. At this point, you can consider the whole operation a success.

Login into the admin panel, go to "Themes" and activate your new theme.

Welcome back!

You've been logged out.