Grav – A Modern Flat-File CMS

09Grav is an open source flat-file CMS that we have started experimenting with for client documentation. Since it requires no database, it is a simple and great alternative to providing documentation without using separate .doc files. The search feature is especially nice for when you want to search through all documentation.

Demo site for GRAV rtfm skeleton: https://demo.getgrav.org/rtfm-skeleton/basics/overview

 

Here are some things we’ve learned along the way:

Installing Plugins:

Admin Panel and Editor are very important plugins to have.

Admin Panel creates an admin dashboard at URL sitename/admin. From here, you can install other plugins, edit pages, manage users, and change configuration settings.

Install by going to your GRAV root folder in a terminal and calling your php.exe with “bin/gpm install admin”


In our case, the php.exe used was within my xampp folder.

Editor is a very useful plugin that provides a “Edit” section in the admin sidebar that allows any authorized users to modify any PHP, Javascript, CSS, Twig, Markdown, and YAML files. This allows for easy editing of any file directly from the admin dashboard!

 

Install by going to your GRAV root folder in a terminal and calling your php.exe with “bin/gpm install editor”

 

CSS:
To modify the css, access user/themes/learn2/css-compiled/theme.css

In this case, we modified the file to left align all my elements by changing the #chapter ID since my page files are chapter.md. This can be achieved by changing these four “center” properties to “left”

(Before) Center aligned:

(After) Left aligned:

Another case is when we modified sidebar font-size by modifying #sidebar ul.topics > li > a in css-compiled/theme.css

Sidebar Logo (top left):
To change the sidebar logo from default GRAV image, access user/themes/learn2/templates/partials/logo.html.twig

To change the admin sidebar logo from default GRAV image, access: user/plugins/admin/themes/grav/templates/partials/logo.html.twig

Replace what is in the file with the SVG code of the image. This was done by converting a PNG to SVG using https://www.pngtosvg.com/

Example of what SVG looks like:

Sidebar:

To modify the sidebar on the left, access user\themes\learn2\templates\partials\sidebar.html.twig
In this case, we wanted to remove the check marks indicating that we had visited that page along with the “Clear History” button on the bottom of the sidebar.

This can be done by removing the relevant lines in the file.

Where to keep your images
We ran into an issue where the images in the images folder would disappear upon caching. This was due to the images folder being in the wrong place. Even though there is a default “images” folder in the root folder, this is not the place to store your images.

Per the official Grav documentation, the images folder should be placed within user/pages:

Do not put images in here:

Instead put them in user/pages/images as depicted here:

On the pages themselves (.md files), link to the images by going up one folder and accessing the images folder with the format (..\images\imagename.png):

 

Be careful when using underscores (“_”) in the .md file
In markdown, surrounding a word with underscores will result in italicizing that word. This could become an issue since many files we deal with use underscores to separate timestamps from the file name.

Take this line for example:

Based on that code, we want the page to look like this:

Instead we get an unwanted italicized word and the removal of an underscore between CODE and RELATION:

The problem can be fixed by “escaping” the underscore by putting a backslash in front of it. Keep in mind that even if we were to escape the underscore between CODE and RELATION, the Markdown language would then try to find the next underscore and would italicize all words in between the underscores (marked in green).

This code:

Will use the underscores boxed in green to italicize all in between them (and removes the underscore in front of “configuration”):

To resolve this, make sure to escape all underscores:

Grav File Uploads

In admin panel, we can add users with these 2 permissions (admin.login and admin.pages):

This creates a user who can log into the admin panel and can edit pages.

When these users go to edit the pages, there is a section that allows media uploads.

“Edit page” page:

These users can also access the “edit page” page through the edit links on the site itself:

These are the files types supported by Grav:

(Although csv is not listed here, it was able to be added as a xml media type and verified to be working)

Once you upload the file and save the page, anyone who has access to this “edit page” page can download/view the file by clicking on the eye “View” icon:

The uploaded files go into the same directory as the markdown page itself.

Clicking the + “Insert” icon will insert the file in the page like so:

Which looks like this on the page:


Clicking it displays the file on the page for .txt, .pdf, .json and .csv. Downloads it immediately for .docx files (these are the 5 I tested):

Issue: When clicking the “View” eye icon for .txt files, there is an error regarding permissions. (It works fine when actually inserted into the page and clicked on from there)

Clearing Cache

CLI commands:
cd ~/webroot/my-grav-project

bin/grav clear-cache