As promised, today I'm going to start covering the process of setting up a development environment utilizing GitHub to manage the code throughout the development life cycle, resulting in publishing to a live site.

As I blogged about the other day, as a web developer, the most efficient and more reliable development strategy is to develop locally, then push your local development to your production site. If you have not ready my post on Grav Development Strategy, you might want to read that first.

Over the course of this two-part series, we will cover the process from start to finish, and I hope to show you that this process is one that will enable you to develop and maintain your site more efficiently.

Let's get started with the first part that is going to focus on getting your local web server set up, Grav installed, creating a new theme, and making some customizations.

In the second installment we will cover taking our modified Grav setup to a live production environment using GitHub.

Get Grav Running Locally

As avid Grav-ites and followers of the RTFM strategy, I'm sure you've already read both the installation instructions and the basic tutorial for Grav. Just to be complete, we will go over the essentials again.

Install a Web Server

To develop locally you obviously need a web server on your computer. Luckily this is not that difficult as there are plenty of options no matter what platform you develop on. I'm a mac user so I will use MAMP, but even for Windows, I recommend trying MAMP for Windows because they both just work.

After you have downloaded the MAMP installation package, you should run the MAMP application and you should be greeted with a simple control panel:

Just click Start Servers to get the ball rolling and start up the servers. If everything goes as planned you should be greeted by the two grey boxes in the top-right of the panel, as well as the button you just pushed, turning green. At this point you can click the Open WebStart page button and you should be greeted by a welcome page running on your new local webserver.

Before we go any further, let's check a couple of configuration preferences to ensure Grav will run optimally. If you click the Preferences.. button on the control panel, you can configure how MAMP will operate. You can configure the ports Apache will run under via the Ports tab, so let's leave MAMP to use it's default 8888 port for Apache. Next we will configure which version of PHP to run and what cache to use via the PHP tab. We're going to choose the latest PHP 5.6 version and also enable OPcache for our PHP caching. Caching improves performance dramatically, so don't forget to enable it (it's not on by default). Your servers should automatically restart after making any changes.

Installing Grav Locally

Next you need to download Grav itself, and for the sake of having something more visual to work with, we will download the blog skeleton ZIP package from the Grav downloads page. This is a ready-to-go package that includes the latest version of Grav, sample content, the Antimatter theme, and an assortment of plugins required to function.

Move the grav-skeleton-blog-site-v.zip file to your /Applications/MAMP/htdocs folder (C:\MAMP\htdocs on Windows) and extract it. This will create a folder called grav-skeleton-blog-site, but rename that folder to grav-blog, for short. At this point you should be able to point your browser at your newly installed Grav site: http://localhost:8888/grav-blog.

If you have been following along, you should see the blog site running.

That wasn't that hard was it?

Some Initial Development

Grav should now be running successfully, but let's proceed by making some modifications to our content, and then some simple theme tweaks to make this instance more unique.

Turn on Debugger

First though, I want to enable the Grav Debugger on my local environment. This gives me lots of information about how Grav is running including performance information as well as status messages.

You can quickly enable this by changing the debugger: enabled: value in user/config/system.yaml, however the better approach is to create a user/localhost/config/system.yaml and enable it there. This utilizes Grav's Environment Configuration to ensure the debugger is enabled only for my local development environment.

You can use any editor but I like to work with Sublime Text for quick text changes (PHPStorm for hard-core PHP development). I'm going to open the entire grav-blog folder up in sublime by dragging it on to my Sublime Text application icon.

Next create a system.yaml file in the user/localhost/config/ folder (you will need to create this folder). Then put the following YAML code for the contents of this file:

debugger:
  enabled: true

Because Grav doesn't automatically update the cache when you create new environment folders (a performance optimization), you must clear the cache manually this first time. However, this is a great opportunity to introduce you to a powerful feature of Grav, the Grav CLI command!

You will need to launch the Terminal application (cmd on Windows), and change directory (cd) to our Grav site by typing: cd /Applications/MAMP/htdocs/grav-blog and hitting return.

Then simply type bin/grav clear-cache and you should get some messages about Grav clearing out the relevant cache locations:

Keep this terminal window handy! We will use it again.

If you reload your browser you should be greeted with a grey Debugger Bar at the bottom of the page. Clicking on one of the tabs will open the bar and give you more details. The time-line along with the total processing time can be particularly useful during development to ensure good performance.

Modify Blog Header

Next, let's modify the current My Gravtastic Blog title.

In your text editor, open up the user/pages/01.blog/blog.md file and change the text below the YAML header to something else:

# Mountain Vacation
## Amazing **Photos** and **Ramblings**

Save this file, and reload your browser. Grav should of detected your changes, and rebuilt the page cache (check the Messages tab in the Debugger). Your browser should be displaying your modified page.

Create a Custom Theme

Now, let's try something a bit more ambitious! We want to modify our theme to have a new blog header image and also a new link color that matches the image a little better.

The first thing we should do is create our own theme based on the default Antimatter theme. This is because we really shouldn't modify the default theme directly. Any updates to this theme could overwrite any customization changes we have made.

So make a copy of the user/themes/antimatter folder and call the new folder user/themes/mytheme (or whatever name you want!). In this new folder you created are two files we need to rename because they need to match the name of the theme folder: antimatter.php and antimatter.yaml. Rename these to mytheme.php and mytheme.yaml respectively. Next open the mytheme.php and adjust the contents to properly reflect the new name:

<?php
namespace Grav\Theme;

use Grav\Common\Theme;

class Mytheme extends Theme
{

}

And then do the same for the YAML file:

enabled: true
color: blue
dropdown:
  enabled: false

streams:
  scheme:
    theme:
      type: ReadOnlyStream
      paths:
        - user/themes/mytheme

The next step is to tell Grav we want to use our new theme rather than Antimatter. So open up the user/config/system.yaml file in your editor and change the line that references antimatter to now reference mytheme:

home:
  alias: '/blog'

pages:
  theme: mytheme
...

If you were to reload your browser now, and you inspected the source, you would see references to /grav-blog/user/themes/mytheme indicating that your are now using your new theme.

I already found a great new header image from unsplash.com. I downloaded it, renamed it, and dropped my new sunset.jpg into the user/pages/01.blog folder, the next step is to change the blog twig template to use it. So open up the user/themes/mytheme/templates/blog.html.twig file in your editor, and locate the following line:

{% set blog_image = page.media.images|first.grayscale().contrast(20).brightness(-100).colorize(-35,81,122) %}

This line is telling Grav to load the first image of this page, and apply some image manipulations to it. We don't need all that so change the line to this:

{% set blog_image = page.media['sunset.jpg'].brightness(-50) %}

This explicitly tells the template to use the sunset.jpg image and just darken it a little so the white text has good contrast. Reloading the page yields results!

The last thing I want to do for my theme is to change the text link because it doesn't really go that well with our new blog header. There are a number of ways you can do this, but the best way is to change the SASS variable. To accomplish this you will need to install SASS or use a 3rd party GUI application. I personally find the terminal version of SASS to be fast and simple, so just follow the instructions on the SASS web site to install it.

Once you have SASS installed, start a new terminal session and navigate to your theme and run scss:

$ cd /Applications/MAMP/htdocs/grav-blog/user/themes/mytheme
$ scss --watch scss:css-compiled

This will continuously run a process that watches for any file changes in the scss/ folder and compiles the CSS into the css-compiled folder. No fuss no muss!

Now to change the link color. In your editor open up the file user/themes/mytheme/scss/configuration/template/_colors.scss and edit the 3rd line:

$core-accent:                   #E15E0E;

This hex value is a sort of burnt orange color that ties in nicely with our new header. Upon Saving this file you should notice some activity in your terminal where you are running scss. You should see something like this showing you where changes were detected and which files were written.

Now when you reload the browser you should see your theme updated with the new link color!

Next Steps...

Part 2 of this series will cover the next steps in the development process. We will go over setting up a repository in GitHub and then pushing your Grav site into this GitHub repository. After that we will go over committing incremental changes to the repository, and also setting up your production site with a GitHub posthook to automatically update when you push changes. So stay tuned!