While trying to visualize my flipped-LMS approach using an open and collaborative platform, it’s become apparent that I am looking at two distinct, though related, models.


For my situation, I use the flat-file CMS Grav to provide an open and collaborative platform when using a flipped-LMS approach.

As a modern flat-file CMS, Grav can take full advantage of today’s ecosystem of open and collaborative editing services, such as GitHub or GitLab. In this article we will look at how to easily use Grav with GitHub Desktop (which uses GitHub and Git for source control) and the automatic deployment service Deploy to result in a very efficient, open and collaborative workflow. No scripting or command line interactions will be required, I promise.

This guide is now outdated. View the updated GitHub & GitHub Desktop tutorial on the new learn.hibbittsdesign.org site.

As an educator, the use of a service such as GitHub to store an online course companion is very appealing as not only does it support an open practice but also enables students to control the very learning environment that they are using. I first described this workflow in my earlier article My Dream Workflow as an Instructor.

Before you start this tutorial I suggest you first get your Grav site up and running locally using MAMP, as outlined in Running Grav Locally with MAMP. By utilizing MAMP you will then have a complete, local version of your course companion site running on your computer that can be easily updated and then deployed to your Webserver.

This tutorial should take about 15 minutes, and once completed you will have an efficient, open, and collaborative workflow for yourself and your students!

Step-by-step instructions

  1. If you do not done so already, sign up for a GitHub account.

  2. Download the GitHub Desktop client for your computer (Mac or PC), and once it is installed launch the application and proceed with the setup process to enter your GitHub account credentials.

    GitHub Desktop setup welcome
    Figure 1. GitHub Desktop setup welcome.

    GitHub Desktop connect to GitHub
    Figure 2. GitHub Desktop connect to GitHub.

  3. Assuming you already have a Grav site present on your computer (and preferably one that is already viewable via MAMP), you next need to create a GitHub Repository of your site. It is recommended that if this is the first time you are using GitHub with Grav that you add the entire Grav site to GitHub, but other approaches are possible such as only storing the “user” folder (see the provided additional resources at the end of this article for more options).

    GitHub Desktop main window
    Figure 3. GitHub Desktop main window, displaying the included tutorial.

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

    GitHub Desktop add Repository dialog
    Figure 4. GitHub Desktop add Repository dialog.

    GitHub Desktop local Repository added
    Figure 5. GitHub Desktop local Repository added.

  4. 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”.

    GitHub Desktop first commit
    Figure 6. GitHub Desktop first commit.

  5. Since this is your first commit to your repository, the “Publish” button (upper-left of main window) will need to be also pressed to actually perform the actual file updates. Once the “Publish” button is pressed enter a short description for your new GitHub repository and then select which GitHub account you want to publish to (if you have multiple accounts).

    GitHub Desktop repository details dialog box
    Figure 7. GitHub Desktop - repository details dialog box.

    GitHub Desktop publishing the repository
    Figure 8. GitHub Desktop publishing the repository.

    GitHub Desktop - repository published
    Figure 9. GitHub Desktop repository published.

  6. Once this process is complete you should now be able to view your Grav site files stored on GitHub - please do this now to ensure that everything went as expected. If you have any issues during this process you may find more detailed GitHub Desktop client support information at https://help.github.com/desktop/.

    GitHub repository of your Grav site
    Figure 10. GitHub repository of your Grav site.

  7. The final step in this process is to trigger an automatic deployment of any changed GitHub files to your Webserver. I recommend you use a Web service that provides this functionality - such as Deploy or Buddy. You can learn how to set up Deploy for use with GitHub in the Deploy support article How do I Start an Automatic Deployment from GitHub? and how to set up Buddy for use with GitHub in the Buddy support articles How to integrate Buddy with GitHub? and How to upload files to FTP/SFTP? .

Congratulations! With the above steps completed you now have a Grav site which you can run and test locally (using MAMP), and with only one click in the GitHub Desktop application have any changed local site files updated in your GitHub repository and then have them automatically pushed to your Webserver hosting your Grav site (via either Deploy or Buddy). In my experience, I can make an update to my Grav site and sync changes to GitHub for automatic deployment to my Webserver in as little as 30 seconds.

 GitHub Desktop repository changes screen
Figure 19. GitHub Desktop main window. When any changes are detected they will be displayed on this screen and can be pushed to GitHub when the “Commit and Sync master” button is pressed.

Students can also now make suggested changes to your Grav site via GitHub or GitHub repository file links provided in your Grav site (see the bottom of this example page at http://paulhibbitts.net/cmpt-363-153//resources). GitHub will provide an excellent view of proposed changes, which you can immediately accept or start a further discussion about these possible changes with the student submitting them.

You can press the GitHub Desktop client “Sync” button (which replaces the “Publish” button you previously used) in the GitHub Desktop client to also download any changes made to the online GitHub repository down to your own computer.

Interested in learning even more about using Grav with GitHub? Check out these two super-informative posts on the Grav Blog:

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.

    Grav Learn2 Theme
    Figure 1. Grav Learn2 Theme.

    Grav Admin Panel Dashboard
    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

    Example GitHub repository
    Figure 3. Example GitHub repository, containing only the “Pages” folder.

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

  1. 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.

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

  2. 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). Editing Overview site page on GitHub
    Figure 5. Editing Overview site page on GitHub, which when completed will result in a Pull Request.

  3. 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. Review submitted Pull Request on GitHub
    Figure 6. Review submitted Pull Request on GitHub, showing GitHub’s super-useful file changes preview.

  4. 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. Updated site page - Overview
    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’.

I’ve been trying to formulate a sustainable approach of an open design practice for my experience design work in the education field, and I think I am getting closer to defining a workable approach:

Interested in learning more about open business models? Be sure to check out Made With Creative Commons on Medium.

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:

Traditional LMS Implementation       Flipped-LMS Approach
Institutional Control Instructor & Student Control
Closed Open
Fixed Pliable
Solitary Collaborative
Stationary Portable

So, why would course facilitators want to utilize a flipped-LMS approach?

Here are three primary reasons that come to mind:

  • To support pedagogical goals unmet by current LMS/platform
  • To increase capability of access, sharing and collaboration
  • To deliver a better student (and facilitator) experience

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.

Step-by-step Instructions

  1. If you do not have an existing Grav site on your computer, download a Grav Skeleton at (https://getgrav.org/downloads/skeletons) and extract the downloaded archive file

  2. Create a folder called ‘MAMP Websites’ in your ‘Documents’ folder

  3. Copy the entire Grav folder into your ‘MAMP Websites’ folder

  4. Launch MAMP (but do not press the ‘Start Servers’ button yet)

  5. Press the MAMP ‘Preferences’ button

    MAMP startup Screen
    Figure 1. MAMP startup screen where the ‘Preferences’ button is located.

  6. Press the ‘Web Server’ tab in the ‘Preferences’ dialog

    MAMP preferences dialog
    Figure 2. MAMP preferences dialog, with the ‘Web Server’ tab on the far top-right.

  7. 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

    MAMP Web server tab
    Figure 3. MAMP Web server tab, with the select folder button represented by a folder containing three dots.

  8. Press the MAMP ‘Start Servers’ button (as shown in Figure 1)

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:

  1. Launch the MAMP application - if MAMP is already running, press the ‘Stop Servers’ button

  2. Press the MAMP ‘Preferences’ button (see Figure 1)

  3. Press the ‘Ports’ tab in the ‘Preferences’ dialog

    MAMP ports panel tab
    Figure 4. MAMP ports panel tab.

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

  5. 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).