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
- Access to Window's Command Prompt
- XAMPP or something similar
On GitHub, create a new repo named
mythemeis 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.
grav-admin, cut the
userfolder and paste it right next to grav-admin.
At that point, your project folder should look like this:
myproject grav-admin user
- Clone your theme repo in the project folder, next to the other ones so it looks like...
myproject grav-admin grav-theme-mytheme user
- 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
- Dump the entire content of
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.phpfile name and any reference to the theme inside the PHP code (make sure you follow capitalization).
- Erase the content of CHANGELOG.md and start fresh with version v0.1.0 (or whatever you think is best).
- Replace references to Wheat in
blueprints.yamland add your own informations.
- Delete the content of
CACHEvariable name using your theme name and version.
thumbnai.jpgwith 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
developand publish it.
- From here on out, commit all changes to the new
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.