Exploring and Building Open [Source] Software for Learning Ecosystems

Experience Design / Education / Multi-device / Grav CMS

Once you start using Grav you will also (more than likely) start using Markdown more than you used to. Wouldn’t it be great to apply your new Markdown skills to other aspects of your work? Well, recently I was introduced to the Markdown-based slides Web app swipe.to (thank you Bryan!) and I’ve really enjoyed using it so far.

Like any other Grav theme, both of the included Course Hub themes (‘Course Hub Bones’ and ‘Course Hub Bootstrap’) can be visually customized using CSS and/or altering their Twig template files. However, if you make changes directly to the Course Hub theme these will be overwritten when that Course Hub theme is updated. So, what to do?

With Grav being a flat-file (no database) CMS tech-savvy educators have a wider range of possible development and deployment options for their Grav Course Hubs than most other database-driven systems. Recently I’ve been exploring an on-line alternative to my currently preferred local development approach, so I thought I would share both together for easier comparison. Both approaches will let you safely develop and test your Grav site before deploying changes to a live production server.

In this article, we will look at how to use Grav with GitHub Desktop and GitLab. Unlike GitHub, you can install GitLab onto your own server, which is an attractive option for many higher education institutions. A locally hosted version of GitLab is used in this walkthrough.

Speaking of Higher Ed folks, if this process looks out of your comfort zone then likely someone in your local IT services should be able to help you get things going pretty quickly by just following this tutorial themselves.

You will be required to enter a few commands into your Mac or PC command line interface (CLI) during this the process, so warm up those typing fingers and let’s get going.

Download the GitHub Desktop client for your computer (Mac or PC), and once it is installed launch the application. Since you will be using GitLab, and not GitHub, you can skip the setup process at this time.

Figure 1. GitHub Desktop setup welcome.

Once the GitHub Desktop application is installed, you will need to install it’s command line tools. This option can be found in the GitHun Desktop’s ‘Preferences’ dialog on the ‘Advanced Panel’ - look for the ‘Install Command Line Tools’ button and then press it.

Using your Web Browser head over to your local GitLab install, sign in and then create a new repository by pressing the “New Project” button.

Figure 3. GitLab welcome message.

Next, enter the name of your new project (repository). Consider the name of the Grav project you will eventually be storing when choosing the name. Once you enter the project name press the ‘Create Project’ button.

Figure 4. GitLab new project.

You will next need to make the initial commit to your newly created GitLab project. Launch the command line interface for the Mac OS, which is the ‘Terminal’ app, or if you are on Windows launch the ‘Git Shell’ app which would have been installed along with GitHub Desktop (within the same application folder).

Figure 5. Mac OS Terminal application.

To streamline the need to navigate directories during this process, I would suggest you place your previously unzipped Grav Skeleton folder to where you wish to eventually maintain it (e.g. in your ‘Documents’ folder). For this operation you will be using the ‘cd’ command, which is for change directory. In your CLI enter ‘cd’, press the space bar, and then drag-and-drop the folder that contains your Grav Skeleton folder (not the actual Grav Skeleton folder) onto the CLI window. With the full path to the folder now after the ‘cd’ command press the ‘Return’ key.

To make sure you are at the correct directory level, you can use the ‘ls’ command, which is for listing the files stored in a directory. In your CLI, enter ‘ls’ and press the ‘Return’ key. You should see the name of your Grav Skeleton folder in this list (e.g. within your ‘Documents’ folder).

Figure 7. Mac OS Terminal application with ‘ls’ command entered.

Now you are ready to link your Grav Skeleton folder to your GitLab repository by copying the hidden ‘.Git’ folder from the cloned repository to your actual Grav Skeleton folder. Return to your Browser, scroll down until you see the ‘Create a new repository’ information area, and copy the first line of text in that box (e.g. ‘git clone git@csil-git1.cs.surrey.sfu.ca:paulh/grav-skeleton-blog-site.git’).

Figure 8. GitLab project, top of page.

Figure 9. GitLab project, bottom of page.

Return to your CLI window, paste the text you just copied (the first line of text in the ‘Create a new repository’ information area), press the spacebar and then enter the text ‘temp’. This command will clone your GitLab repository to your computer within a folder called ‘temp’. Press the ‘Return’ key to run the entered command. You may also be prompted to enter your GitLab username and password for this step.

After a short period of time a message should be displayed about the status of the Git clone command, such as ‘done’.

Figure 11. Mac OS Terminal application git clone command completed.

We now need to make the Grav Skeleton folder the location of the repository on your computer, rather than the empty temp folder we just created. To do this, we enter ‘mv temp/.git’, plus a space, then the name of your Grav Skeleton folder, plus a space, followed by ‘/.git’. This operation will by copy the hidden ‘.Git’ folder from the cloned repository to your actual Grav Skeleton folder.

Figure 12. Mac OS Terminal application move folder command entered.

Figure 13. Mac OS Terminal application move folder command completed.

Now that you have your GitLab Git repository as your Grav Skeleton folder, you can use GitHub Desktop to easily and quickly send any updates back to the repository on GitLab with just a click of the button (no more CLI commands are required!).

Return to the GitHub Desktop app, and press the “Add a Repository” button (upper-right plus(+) sign in the main window) in the GitHub Desktop client, then select the “Add” tab within the displayed dialog box, and press the “Choose…” button to select the folder containing your Grav skeleton.

Figure 14. GitHub Desktop add repository dialog.

Figure 15. GitHub Desktop local repository added.

You are now ready for the first commit to your new GitHub repository. Whenever you make a commit you will need to include a brief text summary - as this is your first commit enter the text “First commit.” into the “Summary” text box (above the “Description” text field), and then press the button “Commit to master”.

Figure 17. GitHub Desktop first commit.

Since this is your first commit to your repository, the “Publish” button (upper-left of main window) may need to be also pressed to perform the actual file updates. Once complete, refresh your GitLab Project page to see the updated files.

Figure 18. GitLab Project Page with updated files.

Congratulations! You now have a Grav site stored on a GitLab repository.

As a next step you should explore options of how to automatically deploy updated files stored on GitLab to your Grav site Webserver. My current favorite service for this is Deploy and you can learn how to set it up for use with GitLab in the Deploy support article How do I start an Automatic Deployment from Gitlab?.

Alternatively, with a little PHP and server access knowledge you can do this only just using Webhooks (which are supported by GitHub, GitLab, and some other Git repository services) - read the “Automatic Webhook” section within the Grav blog post Grav Development with GitHub - Part 2.

Recently I’ve been exploring online (aka “cloud”) IDE’s for use with my various Grav sites and to also recommend for other educators who use Grav with GitHub (as I do). Yesterday I happily discovered SourceLair, which provides a straightforward online environment to develop and test a variety of Web project types all within your Browser (or in my case on my Chromebook). Other noteworthy highlights about SourceLair include a full-screen Terminal and a public URL which can share with others to view your in-development work.