Starting a new project

This article is a work in progress. Some or most of it is still evolving and you should expect some level of inaccuracy.

What you'll need...

  • A PC running Windows (but I'm sure you can figure it out on a Mac)
  • A GitHub account
  • A cool project name
  • Internet
  • Access to the Command Prompt
  • XAMPP or something similar
  • About 30 minutes

Getting started

  • Go on GitHub and create a new repo named grav-theme-mytheme (replace mytheme with your cool project name), in lowercase. (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.)

  • 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:

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).
  • 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 CHANGELOG.md 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.

Symlinks

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 127.0.0.1/myproject). 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.

This article is a work in progress. Some or most of it is still evolving and you should expect some level of inaccuracy.

What you'll need...

  • A PC running Windows (but I'm sure you can figure it out on a Mac)
  • A GitHub account
  • A cool project name
  • Internet
  • Access to the Command Prompt
  • XAMPP or something similar
  • About 30 minutes

Getting started

  • Go on GitHub and create a new repo named grav-theme-mytheme (replace mytheme with your cool project name), in lowercase. (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.)

  • 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:

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).
  • 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 CHANGELOG.md 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.

Symlinks

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 127.0.0.1/myproject). 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.