HTML Template to GravCMS, Part 1

Introduction

This post (and the ones following) documents how I converted a nice HTML theme called Editorial from HTML5 Up to a usable theme for Grav CMS. You can find the finished Grav theme here.

The following process is the one I think makes the most sense to me. As is the case in most web development, there are plenty of different ways of going about this conversion.

A Quick Note About Licensing

Something to keep in mind is that all themes from HTML5up are licensed under the CC3 license. We need to make sure to give HTML5 Up credit in our ported theme! If you are looking for attribution-free themes from the same designer, head to his other site, Pixelarity.

Make sure to follow whatever license your source material comes from. No really....no really. Follow the license.

Locally Installed Tools

  • Composer
  • Docker (required for ddev)
  • Local web dev server that supports php (I chose ddev-local)
  • Code editor (I chose VSCode. See the section on setting up the environment for what extensions I use.)
  • Source code management software (I'll be using git)
  • (optional) Gulp (Used as a CSS pre-processor, along with sass)

Environment Setup

Grav project folder

I personally create a folder under my home directory for all my projects. I then run

$ cd /home/projects
$ mkdir grav_root
$ cd grav_root

where grav_root will be the name of your Grav devlopment folder. Going forward, I will refer to this folder location as GRAV_ROOT in my tutorial, without the prepending folder structure.

ddev Project Setup

Follow the instructions for your OS platform to install ddev. Once installed, change directory to your GRAV_ROOT and then run:

$ ddev config

This command will prompt you regarding this project. Default answers are sufficient. The type of project is php.

Once complete, run

$ ddev start
$ ddev ssh

You'll be ssh'd into the php webserver of your dev server, defaulting to the html folder. This folder is the shared folder of your GRAV_ROOT. While here run

# composer create-project getgrav/grav .

This will install the latest stable version of Grav (v1.6 branch as of writing this). Once the installation is complete, exit from the webserver to return back to your host machine. If you visit the url of your project, you should see a basic Grav instance webpage.

You can find out more information of using ddev and grav at Grav's excellent documentation site.

Grav plugins

Let's install some basic Grav plugins by ddev ssh-ing back into the webserver.

$ ddev ssh
# bin/gpm install admin devtools simplesearch auto-date -y
# exit
  • admin: provides a web-based GUI for managing this site
  • auto-date: Automatically adds date meta-data to new pages.
  • devtools: CLI tool for creating a new plugin/ theme.
  • simplesearch: The Editorial theme has a search box. We'll leverage SimpleSearch for that functionality.

Grav Theme Setup

The devtools plugin is a great tool for creating new plugins and themes.

$ ddev ssh
# bin/plugin devtools new-theme
# exit

Answer the prompts from the CLI. The project name must be unique. If you attempt to choose an existing name in Grav's package manager (gpm), the tool will throw you an error.

  • Theme Name: Editorial
  • Theme Description: Grav port of the Editorial theme from HTML5Up.net
  • Developer Name: Jeremy Gonyea
  • GitHub ID: jgonyea
  • Developer Email: jeremy.gonyea@gmail.com
  • pure-blank

That last line is important, as we want to start with as clean of a slate as possible to dump our HTML5Up theme into.

The GRAV_ROOT\user folder is where all plugins, themes, configs, etc. are placed. You should see your new theme under the themes folder. I'll call this path THEME_ROOT.

Let's also start tracking theme changes via git.

$ cd THEME_ROOT
$ git init
$ touch .gitignore
$ git add .
$ git commit -m "Initial pure-blank theme commit"

Code Editor Setup

I personally enjoy using VSCode for editing Grav sites. Point VSCode at GRAV_ROOT. There is a plethora of plugins you can use to assist your coding, so I won't go into those here.

$ cd GRAV_ROOT\user
$ code .

Edit your THEME_ROOT.gitignore file to include node_modules so we don't accidentally commit those to the repo.

Setup Stage Recap

We're planning on converting an HTML-based template from HTML5up.net to a Grav CMS theme. We've setup a local environment for hosting the site (ddev), installed the Grav site at GRAV_ROOT, created a blank theme at THEME_ROOT, and have started a git repo at THEME_ROOT. VSCode is ready for editing our files.

In Part 2, we'll grab the template and start porting!

Read on for more in this series "HTML Template to GravCMS":