Exploring and Building Open [Source] Software for Learning Ecosystems

Experience Design / Education / Multi-device / Grav CMS

Recently, I’ve been exploring ways to use the modern flat-file CMS Grav as a simple open publishing tool. Grav is a natural candidate for this usage, as all content is stored as individual files which can be stored on a variety of open and collaborative editing environments (e.g. GitHub).

This article will be substantially updated once the pre-release Git Sync plugin for Grav is officially released (expected in February).

Here is a snapshot of the approach that has produced the best results for me so far:

An instance of Grav running on a Web server, using a slightly modified version of the Learn2 theme. The Learn2 theme is pre-configured with support for content to be stored/maintained on GitHub, although any Grav theme could also be customized to support this ability. The Admin Panel plugin has also been installed, providing the ability to perform easily any needed Grav system updates.

Figure 1. Grav Learn2 Theme.

Figure 2. Grav Admin Panel Dashboard.

A GitHub repository containing only the “Pages” folder of the Grav instance. This results in having only content files (using Markdown) being presented in the repository, bringing a high-level of visibility to the content files of your site for users who wish to interact directly with the GitHub repository. You can view the GitHub repository of my example “Pages” site folder at https://github.com/hibbitts-design/grav-course-hub-starter-kit

Using a GetHub Webhook either through a service such as Deploy, or directly by adding the needed PHP file (see Grav Development with GitHub - Part 2 on getgrav.org), configure a site update to be automatically performed when one or more content files are modified on GitHub.

We now have a simple open publishing system which leverages the power of GitHub! Anytime someone makes a change in the GitHub repository, and you approve of the change, the results will be automatically published to your live site. As well, all of your edits, etc. are available for public viewing and commentary. The content made available on GitHub may also be forked and used for other useful purposes.

It should be noted that you would want to make any significant changes to the chosen Grav theme before you upload the Grav site to your Web server. You can still make changes to the theme once it is running on your Web server, but doing so would require using a FTP program to edit the needed files or copy the updated files from your computer to the site. Alternatively, you could the place the “User” folder on GitHub (or even the entire Grav instance, as Grav is open source) which would also contain any theme customizations, but doing so would reduce the high-level visibility of your content files achieved when only placing the contents of your “Pages” folder on GitHub.

Here is an overview of the flow of someone making a change to your site content via GitHub:

Viewing the Grav site, a viewer can click the provided “Edit this Page” link to propose changes to the page. You can view a live example of this technique at my Course Hub Starter Kit prototype site.

Figure 4. Example site page - Overview, using a modified version of the Learn2 theme with a link to edit the page on GitHub.

Once the viewer has logged into GitHub, they can edit the page and then submit a Pull Request (a request for the site administrator to review and approve the submitted changes).
Figure 5. Editing Overview site page on GitHub, which when completed will result in a Pull Request.

The site administrator reviews the submitted Pull Request, and can approve changes immediately or start a discussion with the author of the proposed changes for further modifications, etc.
Figure 6. Review submitted Pull Request on GitHub, showing GitHub’s super-useful file changes preview.

Once the change is approved by a site administrator of the GitHub account the changes to the GitHub repository will be automatically pushed to the server, where the updated content is available to be viewed.
Figure 7. Updated site page - Overview.

I personally also like to use GitHub Desktop as a point-and-click means to keep a local copy of my GitHub repositories on my local machine so I can use any markdown-enabled application for editing my content files. GitHub Desktop can also sync any changes made to the GitHub repository down to your local machine. You can learn more about my use of GitHub Desktop in my earlier post My Dream Workflow as an Instructor.

Note: The original title of this post was ‘Using Grav as a Simple Open Publishing Tool’.

While every project has different needs, I am finding that database-based CMS platforms such as WordPress are often too complex/feature-laden for the needs of individual educators/publishers. In contrast, flat-file CMS platforms offer more simplicity and control. Here are some of the key reasons I am now focusing on using modern flat-file CMSs for my development work (especially when implementing a flipped LMS approach):

Modern

Modern PHP code (i.e. reliability, speed, extensibility, etc.)

Use of current standards (i.e. Markdown, Twig, YAML, etc.)

Modular/customizable content chunks (i.e. reuse of content)

Further separation of content (i.e. files) from presentation

Flat-file

No database means less (or no) IT involvement needed

Content stored in text files rather than in a database (often translating into faster page access times)

Takes full advantage of the collaborative ecosystem now available (i.e. GitHub)

Increased portability, as moving a site now only requires simply copying files to another location

All template and content files are 100% version controllable

So, what is my favorite modern flat-file CMS right now? Without a doubt the rising star in this space to me is Grav, which is actually more of a web-platform than a traditional CMS. After trying out a number of flat-file CMSs, including Kirby and Statamic, I found Grav has a perfect mix of flexibility and ease of use for web-savvy educators. In addition, Grav is backed up with solid documentation and community support.

In a recent discussion the question of how a traditional LMS implementation compares to a flipped LMS was asked. Here are my initial thoughts so far, based on my experiences with several institutional LMSs and using the flat-file CMS Grav in a flipped-LMS approach:

One of the (many) great things about using the open source CMS Grav for a flipped-LMS approach is that no database is required, which makes running a local copy of Grav on your computer for testing purposes a very straightforward process. This also makes deployment to a Web server a breeze - just a simple folder copy.

In this brief article we will look at how to use MAMP, a tool to safely run a PHP server on your computer, to view Grav sites locally on your Mac or Windows PC.

Change the ‘Document Root’ MAMP preferences setting from the default value ‘htdocs’ within the MAMP application folder to the ‘MAMP Websites’ folder that you previously created within ‘Documents’ by pressing the select folder button (a folder containing three dots), choosing the folder, and then pressing the ‘OK’ button

With MAMP installed and running you can now view your Grav site(s) locally. Launch your Web Browser, enter the URL http://localhost:8888 and then choose the displayed Grav folder name. That’s it! If you downloaded a Grav Skeleton with the Admin Panel pre-installed you will be prompted to create your administrator account.

Additional MAMP Setup Options

If you would prefer, you only need to enter ‘http://localhost’ in your Web Browser to access your MAMP htdocs directory listing, then do the following:

Change the value in the ‘Appache Port’ field from the default value ‘8888’ to ‘80’ (no quotes)

Press the ‘OK’ button

If you are curious about how a local copy of Grav can be used with GitHub/GitHub Desktop for super-easy deployments while fully supporting student collaboration, check out the article Using Grav with GitHub Desktop (and Deploy).