Linux at the office – Grav: een flat-file content management systeem voor Markdown bestanden

Grav is een gemakkelijk te gebruiken, modern open source content management systeem, dat gebruik maakt van platte-tekst Markdown bestanden. Dankzij de grote hoeveelheid plug-ins en themes maak je hier vlot een eenvoudig te onderhouden en snelle website mee. 

De meest bekende content managementsystemen, zoals bijvoorbeeld WordPress, Joomla en Drupal, bieden veel mogelijkheden en zijn zeer flexibel in te zetten. Dit maakt deze systemen ook complex, wat niet alleen gevolgen heeft voor de ontwikkelaars, maar ook voor de beheerders en gebruikers. Deze complexiteit maakt de bouw en onderhoud van bijvoorbeeld plug-ins ingewikkeld. Geregeld worden nieuwe kwetsbaarheden gevonden, wat de reputatie van deze systemen niet ten goede komt. Een alternatief vormen de zogenoemde flat-file content managementsystemen, die de data niet in een database opslaan, maar gebruik maken van een verzameling eenvoudige tekstbestanden, vaak in het Markdown formaat.

Flat-file CMS

Er zijn twee manieren om op basis van een verzameling tekstbestanden een website te genereren. Eén methode is om een statische site te genereren. Hierbij wordt na elke wijziging de gehele website opnieuw gegenereerd, waarna de html-bestanden in de directory-structuur van de webserver worden opgenomen. Voorbeelden hiervan zijn Ikiwiki en Jekyll. De andere methode is om de Markdown-bestanden op de webserver te plaatsen, waarbij telkens wanneer een webpagina opgevraagd wordt, deze on-the-fly te genereren. Hier is dus sprake van een dynamische website. Elke methode heeft zijn voor- en nadelen.

Het voordeel van de statische methode is dat de webserver geen scripts hoeft te draaien en alleen maar html-bestanden verwerkt. De webserver kan hierdoor heel simpel zijn en wordt nauwelijks belast. Het nadeel is dat een wijziging in bijvoorbeeld de opbouw van pagina’s als gevolg heeft dat de gehele website volledig opnieuw moet worden gegenereerd.

Het voordeel van de dynamische methode is dat een wijziging in de opbouw van de pagina’s alleen in de template hoeft te worden aangepast, vanaf dat moment zijn alle opvragingen automatisch in de nieuwe vorm. Het nadeel is dat de webserver de Markdown bestanden bij elke opvraging moet converteren naar html. Nu is deze conversie vrij eenvoudig uit te voeren, waardoor dit zonder noemenswaardig performanceverlies kan plaatsvinden. Daardoor kunnen ook grotere en drukbezochte websites, zeker met inzet van geavanceerde cache-technieken, hiermee prima uit de voeten.

Wanneer je later ooit besluit naar een ander soort omgeving te migreren, dan hoef je je weinig zorgen over de uitwisselbaarheid van de content te hebben. Omdat alle data als platte bestanden in een directory-structuur in het standaard Markdown formaat beschikbaar is, is dezege makkelijk en eenvoudig toegankelijk.

Snel en eenvoudig

Er bestaan veel verschillende flat-file content managementsystemen, van heel eenvoudige tot heel uitgebreide, en in uiteenlopende omgevingen, zoals Ruby, NodeJS en natuurlijk PHP. Grav behoort tot de meer uitgebreide systemen, gebruikt PHP en is beschikbaar onder de MIT open source licentie. Grav is ontwikkeld met de focus op snelheid, eenvoud en flexibiliteit. Het gebruikt Markdown bestanden in een directory-structuur om de HTML-pagina’s te genereren welke daarna in verband met de performance gecached worden. Grav gebruikt Twig templates, waardoor de gebruiker de volledige controle over het design heeft, YAML voor de configuratie en Doctrine voor de caching. Samen met de plug-in architectuur van Grav ontstaat zo een zeer flexibel en breed in te zetten platform. Grav is meertalig.

Voor Grav bestaan veel themes en samen met de zogenoemde skeleton packages creëer je snel een website met passende functionaliteiten. Een skeleton is een complete installatiebundel, inclusief een aantal voorgeselecteerde plug-ins en een theme.

Het gebruik van Twig maakt het overigens eenvoudig om zelf je eigen ontwerp te realiseren. Op het moment van schrijven biedt de Grav website 78 themes, 210 plug-ins en 44 skeletons, onder andere voor een blogsite, een webshop, een documentatiesite, een receptensite, een open course site, enzovoorts.

Directory structuur

In Grav bestaat elke pagina uit een eigen subdirectory met daarin één of meer bestanden. De directory-naam is belangrijk. Wanneer de naam met 01, 02, enzovoorts begint, zoals bijvoorbeeld 01.home en 02.about, dan wordt hiervoor automatisch een item in het navigatie-menu aangemaakt, gesorteerd op basis van deze eerste twee cijfers. Wanneer de directory-naam niet met twee cijfers en een punt begint, dan komt deze niet in het navigatie-menu. De directories kunnen genest worden. Stel je wilt in je website een blog opnemen, dan komt in de hoofddirectory een subdirectory 04.blog en in deze subdirectory voor elke blog-pagina weer een aparte subdirectory.

In de subdirectory van de pagina staat het Markdown bestand. De naam van dit bestand bepaalt het template voor de conversie naar de uiteindelijke html. Bijvoorbeeld de bestandsnaam “default.md” levert een pagina in de standaard opmaak op, “blog.md” de opmaak voor de startpagina van de blog en “item.md” de opmaak van de blogpagina’s zelf. Welke templates aanwezig zijn, en daarmee welke bestandsnamen gebruikt moeten worden, is natuurlijk afhankelijk van het theme.

Het Markdown-bestand zelf is opgebouwd uit twee secties. De bovenste sectie, dat met behulp van twee markers, bestaande uit “—“, van de rest is gescheiden, bevat de YAML frontmatter. Dit bevat wat meta-informatie, zoals de titel van de pagina, de menu-naam van de pagina, eventuele begin- en/of einddatum van de publicatie, enzovoorts. Na de tweede marker volgt de content, in normaal Markdown formaat. Afbeeldingen, filmpjes, etc. die in een pagina thuis horen, kun je eenvoudig in de subdirectory van die pagina opnemen.

Grafische interface

Desgewenst kun je de Grav admin omgeving installeren. Dit is een grafische interface, met onder andere een dashboard waarin je wat statistieken te zien krijgt. Denk aan een overzicht van de laatst gewijzigde pagina’s en dergelijke. Verder bevat het een uitgebreide configuratie module, modules om plug-ins en themes te installeren en een grafische tool om de content mee te beheren. Het onderhoud van de content, zoals pagina’s toevoegen en de inhoud van pagina’s wijzigen, kan via de admin omgeving, maar dit is geen noodzaak. Je kunt ook directory-structuur zelf subdirectories aanmaken, bestanden toevoegen en onderhouden. Elke wijziging is direct in de website zichtbaar.

Het voordeel van het gebruik van de admin omgeving is dat je geen kennis over de YAML frontmatter hoeft te hebben. Met een paar muisklikken, maak je een nieuwe pagina aan, kies je het template en de parent en kun je met behulp van een minimalistische webeditor de inhoud van je pagina aanmaken. Wanneer je deze opslaat, wordt in de achtergrond een subdirectory aangemaakt met daarin het Markdown bestand met de juiste bestandsnaam en de juiste YAML frontmatter sectie.

Wanneer je de volgorde van de pagina’s wilt wijzigen, is de admin omgeving een uitkomst. Je krijgt een overzicht van de pagina’s in de huidige volgorde onder elkaar. Je sleept een pagina naar de gewenste plek en wanneer je dit opslaat hernoemt de admin module de betreffende subdirectory’s zodat alles op zijn juiste plek staat.

Taxonomie

Grav biedt uitgebreide mogelijkheden voor het werken met labels en content filters. In de site YAML-configuratie (in de /user directory) geef je op met welke taxonomie types je wilt werken, bijvoorbeeld met het type “Auteur”, “Categorie” en “Tag”. Vervolgens geef je in de YAML frontmatter aan, welke waarden je voor deze types wilt invoeren. Bijvoorbeeld “D. Adams” als Auteur, “Ergernissen” als Categorie en met als Tags “SystemD” en “DBus”. Afhankelijk van het template worden deze onderdelen getoond op de html pagina (zoals bijvoorbeeld Tags bij je blogposts), verder is het mogelijk filters te maken op deze taxonomie types, zodat je bijvoorbeeld een verzamelpagina kunt maken van alle pagina’s geschreven door een bepaalde auteur of van een bepaalde categorie, of een complexer filter waarbij je op een combinatie van meerdere types en/of waardes filtert.

Wanneer je een pagina in de admin omgeving opent, dan vind je onder het tabje “Options” de taxonomie types die je in de site YAML-configuratie hebt opgegeven terug, met voor elk type een invulveld, waar je één of meer waardes invoert.

Formulieren

Grav biedt de mogelijkheid om formulieren in je website op te nemen. De definitie van je formulier, zoals welke velden het dient te bevatten, of deze wel of niet verplicht zijn, enzovoorts, maar ook wat er na het submitten moet gebeuren en wat de pagina na het submitten toont, neem je allemaal op in de YAML frontmatter. Standaard worden twee proces-mogelijkheden meegeleverd, te weten het versturen van een e-mail en het opslaan van de formulier-data als tekstbestand. In de frontmatter geef je de gewenste methode(n) aan en bij het processen als e-mail geef je aan naar welke adressen het e-mail bericht toe moet worden gestuurd. Kies je (ook) voor opslaan, dan wordt in /user/data een directory voor het betreffende formulier aangemaakt, hierin wordt per submit een tekstbestand aangemaakt met de ingevulde data.

De installatie van Grav is zeer eenvoudig. Wij installeerden Grav op een Debian Stretch systeem, met een Nginx webserver en PHP 7.0. De installatie bestaat uit het uitpakken van een zip bestand en het aanpassen van de webserverconfiguratie. Meer is niet nodig. De Grav documentatie biedt voor de meest voorkomende webservers een voorbeeld configuratie. Het installeren van plugins en themes is zeer eenvoudig. Ook het installeren van de updates is super simpel, dit gaat met behulp van een muisklik in de admin module of, naar keuze, een enkel commando op de commandline.

OTAP

Een groot voordeel van de flat-file systeem is dat het eenvoudig is om het onderhoud van de content op een andere plaats te doen dan op de webserver. Omdat de gehele installatie van Grav uit een directory met subdirectories bestaat, inclusief Grav zelf, de plug-ins, themes en de content, realiseer je hier gemakkelijk een OTAP-achtige omgeving mee waarbij het onderhoud van de content, plug-ins, themes en dergelijke geheel gescheiden gebeurt van de productie website.

Je kunt bijvoorbeeld op je lokale netwerk Grav installeren en door één of meer gebruikers laten onderhouden, en na wijzigingen de directory op de webserver synchroniseren. Hierdoor kun je de rechten op de webserver strak inrichten. Je hoeft geen database dumps te maken. Nadat lokaal wijzigingen zijn doorgevoerd en goed bevonden, kunnen deze naar de webserver gesynchroniseerd worden, bijvoorbeeld via rsync over ssh. Zo kun je dus ook eenvoudig updates uittesten, nieuwe themes proberen, etc.

Een ander voordeel is de mogelijkheid om de gehele omgeving in een versie beheersysteem op te nemen, zoals bijvoorbeeld Git of Mercural.

Overstappen

Wanneer je een complexe website hebt in een database gebaseerd CMS, zoals WordPress of Drupal, en daarbij zwaar op veel aanvullende modules leunt om een complexe functionaliteiten mee te realiseren, dan zal Grav geen alternatief zijn. Voor minder complexe toepassingen is de overstap naar een flat-file content managementsysteem het overwegen waard. In vergelijking met conventionele content managementsystemen krijg je met Grav een veel eenvoudiger te installeren en te beheren omgeving én een snelle website. Door het gebruik van een directory-structuur, in plaats van een database, hoef je slechts enkele PHP-modules te installeren waardoor je je geen zorgen hoeft te maken over kwetsbaarheden, zoals SQL-injectie. Grav heeft een uitstekende documentatie. Kijk eens op ‘https://learn.getgrav.org/’. Dankzij deze documentatie en de eenvoud van YAML en Twig is het leuk om met Grav te stoeien. Probeer het zelf!