Pelican – Een open source static site generator.
Een statische website is sneller en veiliger dan een dynamische website. Wanneer je bijvoorbeeld een Raspberry Pi als webserver inzet, is het lichte gewicht van een statische website een belangrijk voordeel. Pelican is een makkelijk te installeren en te gebruiken static site generator geschreven in Python.
Auteur: Matto Fransen
Een static site generator ontkoppelt het content management gedeelte van het publicatie gedeelte. De content beheer je op een lokaal systeem, bijvoorbeeld je desktop computer of je laptop. De static site generator zet dit om in een statisch website, die je vervolgens uploadt naar de webserver. Vergeleken met een dynamische website verschuif je, met het gebruik van een static site generator, een groot deel van de workload van de webserver naar je locale systeem. Het samenvoegen van content, theme, het omzetten naar html code, enzovoorts hoeft de webserver immers niet meer te doen. De webserver kan het zonder database engine stellen, hoeft geen dynamische scripts te interpreteren en serveert simpel kant-en-klare html-bestanden uit, die ook nog eens makkelijk te cachen zijn.
Wanneer je een dynamische website maakt met een content management systeem, zoals WordPress of Drupal, moet je veel aandacht besteden aan het up-to-date houden van de server-side infrastructuur. Deze stack van database, PHP en de bovengenoemde CMS systemen behoren wereldwijd tot de meest gebruikte oplossingen, daarom houden de makers van exploits deze nauwlettend in het oog. Het is zaak om bij het uitkomen van upgrades deze snel te installeren. Doe je dit niet, dan is de veiligheid van je server in gevaar. Steeds meer mensen kiezen om één of meer van deze redenen voor een statische site.
Een statische site bestaat uit platte html pagina’s. Hierdoor laden deze snel in de browser van de bezoeker. Daarnaast heb je geen database en geen dynamische taal, zoals PHP, nodig die je pagina’s on the fly genereert. Wanneer je geen PHP, WordPress en dergelijke installeert, loop je ook geen gevaar door eventuele kwetsbaarheden in deze software. Het ontbreken van dynamische pagina’s zorgt dat je je geen zorgen hoeft te maken over de performance van je webserver en is daarmee geschikt voor eenvoudige hardware, zoals een Raspberry Pi of een Beaglebone Black. Ook zijn statische sites zeer geschikt voor websites met een hoog aantal bezoekers.
Voor je eigen persoonlijke website hoef je voor een statische website nauwelijks eisen aan de webserver te stellen. Elke webserver daemon is prima, ook de lichtgewicht daemons voldoen uitstekend. Wij hebben al een aantal jaar goede ervaringen met Lighttpd op een klassieke Raspberry Pi.
De static site generator Pelican is onder een open source licentie beschikbaar, is geschreven in Python en is platform-onafhankelijk. Pelican is gemakkelijk met pip te installeren op Linux, FreeBSD, OpenBSD en dergelijke en draait desnoods ook op Microsoft Windows. Rondom Pelican bestaat een community van enthousiaste ontwikkelaars en gebruikers, die gezamenlijk een groot aantal themes en plug-ins ontwikkeld hebben. Pelican staat op Github en heeft daar op het moment van schrijven ruim 8.900 sterren.
De content van je website schrijf je naar keuze in reStructuredText of in Markdown. Dit heeft veel voordelen. Je schrijft de content in je favoriete tekst-editor, je kunt ieder willekeurig versiebeheersysteem gebruiken en mocht je later naar een andere omgeving willen, dan ben je verzekerd van een eenvoudige migratie. Emacs gebruikers kunnen in org-mode de content schrijven. Pelican heeft daarvoor een plug-in. Ook is er een plug-in voor het werken met het ascii-doc format.
Je kunt Pelican (nog) meer naar je hand zetten met themes en plugin en Pelican biedt zaken, zoals syntax highlighting en interne links. Het genereert desgewenst een RSS-feed, een tag-cloud, een TOC boven aan de webpagina, enz.
Pelican installeren is gemakkelijk. Je hoeft geen moeilijke omgeving te installeren en hebt geen gedoe met lastige of tegenstrijdige dependencies. Pelican maakt tijdens de quickstart-configuratie een handige Makefile voor je. Daarom adviseren wij om meteen even de build-essentials te installeren. Begin met sudo apt-get install build-essential python-pip. Hierna installeer Pelican je eenvoudig met sudo pip install pelican Markdown.
Hierna maak je in je home-gebied een werkdirectory aan voor het beheer van je website: mkdir ~/mijnsite && cd ~/mijnsite. Hier start je pelican-quickstart. Dit script stelt je enkele vragen en richt vervolgens de directory voor je in. Desgewenst maakt het een Makefile aan, die automatisch je website via bijvoorbeeld ssh of ftp upload of naar Dropbox of Github Pages overzet.
Het pelican-quickstart script maakt uiteindelijk een configuratiebestand ‘pelicanconf.py’ voor je aan, plus een directory met de naam ‘content’ en een directory met de naam ‘output’. Bestanden met de inhoud voor je website maak je in de content-directory. Wij beginnen met een eenvoudige pagina in Markdown formaat.
Open je favoriete editor en maak het bestand ‘content/helloworld.md’ aan. Zet hierin de volgende regels:
Title: Mijn Eerste Pagina Date: 2019-07-19 15:30 Category: Python Tags: pelican, testpagina Summary: Korte tekst voor de index # Dit is mijn eerste pagina Hallo wereld!
Sla dit bestand op. In je werkdirectory start je nu het genereren van de website op met: pelican content. Hierna start je de ingebouwde webserver met: pelican –listen. Open je browser en ga naar http://localhost:8000. Hier zie je nu het resultaat van je noeste arbeid, zie screenshot 1.
Wij gebruiken hiervoor zelf een opzet met Tmux met twee vensters, waarbij we in het ene venster de content beheren en in het andere venster voortdurend pelican –listen hebben lopen. Wanneer je de content aanpast of nieuwe content maakt, en daarna de website opnieuw genereert, dan hoef je het proces pelican –listen niet te onderbreken. Het is voldoende om de pagina in je browser te refreshen. Wellicht ten overvloede melden we nog even dat deze optie alleen bedoeld is voor het testen van je website, niet om deze site wereldwijd te presenteren. Nadat je website klaar is, of een aanpassing naar je zin is, upload je deze naar een geschikte webserver.
Zoals je hierboven ziet, start de Markdown-pagina eerst met een aantal regels, met per regel een veldnaam, een dubbele punt en de inhoud voor dat betreffende veld. Hiermee informeren we Pelican over de metadata voor onze pagina. Na deze metadata kunnen we de inhoud van de pagina verder aanvullen in het gebruikelijke Markdown formaat. Alleen de titel en de datum zijn verplichte velden. Pelican gebruikt de volgende velden: Author, Authors, Category, Date, Modified, Save_as, Slug, Status, Summary, Tags, Template, Title en URL.
In je Markdown document maak je links aan in het formaat [omschrijving](url), dus eerst tussen vierkante haken de linktekst die de gebruiker te zien krijgt, met daarachter tussen ronde haken het adres waar de link naartoe moet wijzen, bijvoorbeeld: [Link naar Linux Magazine](https://linuxmag.nl).
Een lokale link naar een ander document binnen je website maak je als volgt: [Link naar Hello World]({filename}/helloworld.md).
Onder statische content wordt het meer ‘vaste’ gedeelte van je website bedoeld, bijvoorbeeld pagina’s zoals ‘about’, ‘contact’, en eventueel je error-pages. Maak in de content-directory een subdirectory aan met de naam ‘pages’. Hierin maak je bijvoorbeeld het bestand ‘about.md’ aan, voor de about-pagina. Statische pagina’s die niet in het hoofdmenu moeten komen, geef je als metadata ‘Status: hidden’.
Met media, zoals plaatjes, werk je ongeveer op dezelfde manier. In de content-directory maak je hiervoor één of meer subdirectories aan, bijvoorbeeld ‘afbeeldingen’ voor plaatjes en ‘pdf’ voor PDF documenten. In de subdirectories ‘afbeeldingen’ plaats je bijvoorbeeld het bestand ‘tux.jpg’. Deze afbeelding neem je als volgt in je Markdown document op: .
Verder zie je in je gegenereerde pagina een melding dat je sociale links in je configuratiebestand kunt opnemen. In dit bestand zie je deze tekst terug achter de variabele SOCIAL. Deze kun je eenvoudig aanpassen, bijvoorbeeld met je eigen Twitteraccount:
SOCIAL = (('Twitter (#linuxmagNL)', 'https://twitter.com/linuxmagNL'),)
Wanneer je code in je webpagina wilt laten zien, dan maak je dit beter leesbaar met syntax highlighting. Het codeblok neem je op met een indent, dat wil zeggen dat alle regels met een tab of vier spaties beginnen. Als eerste regel in je codeblok neem je een she-bang regel op. zonder pad. Bijvoorbeeld #!sh voor een shell script, of #!perl voor een Perl script, enz.
Pelican gebruikt de Jinja2 template engine. Je kunt hiermee je eigen theme maken. Makkelijker is om één van de vele beschikbare themes te gebruiken. Je begint met het maken van een git clone, bijvoorbeeld in de root van je home-gebied. Hier doe je git clone –recursive https://github.com/getpelican/pelican-themes. Je krijgt hiermee een directory pelican-themes met daarin een aantal themes. Elke theme heeft zijn eigen sub-directory. Door de directory met themes buiten je Pelican gebied te houden (in ons voorbeeld hierboven ~/mijnsite), voorkom je dat je git repositories gaat nesten.
In je configuratie van Pelican, in het bestand pelicanconf.py, neem je een regel op, waarin je het gewenste theme selecteert, bijvoorbeeld: THEME = “/home/<usernaam>/pelican-themes/brownstone”. Wanneer je nu de site opnieuw genereert (pelican content), dan wordt jouw site in het nieuwe jasje gegenereerd.
Wanneer je zelf een theme maakt, dan kun je die via een git pull-request aan de community beschikbaar stellen.
Soms biedt een theme nog nadere configuratie mogelijkheden, waarmee je bepaalde features activeert of deactiveert. Lees daarom altijd even het README bestand van het betreffende theme.
Het installeren van plug-ins gaat op dezelfde wijze als het installeren van themes, je maakt een git clone van de betreffende repository. Ook dit kun je in je homegebied doen. Je maakt de git clone van https://github.com/getpelican/pelican-plugins.git.
In het configuratiebestand pelicanconf.py, neem je een regel op met het pad naar de plug-ins, en een tweede regel met de gewenste plug-ins, bijvoorbeeld:
PLUGIN_PATHS = ['/home/<usernaam>/pelican-plugins'] PLUGINS = [ "tag_cloud", "sitemap" ]
Voor het maken van je website werk je dus met drie directories, een directory voor de plug-ins, een directory voor de themes en de werkdirectory voor het beheer van je website en het genereren van het eindproduct. Deze laatste werkdirectory bevat de configuratiebestanden, een directory met de content, eventueel een directory voor de vaste pagina’s, zoals contact en about en dergelijke, eventueel een directory voor media, zoals afbeeldingen en de output-directory, waarin het eindproduct gegenereerd wordt.
De werkdirectory voor het beheer van je website neem je in zijn geheel in bijvoorbeeld Git op. Je kunt daarbij de output-directory in je .gitignore bestand opnemen. De inhoud kun je op ieder gewenst moment opnieuw genereren.
Door verschillende directories naast elkaar via pelican-quickstart in te richten als beheerdirectory, organiseer je eenvoudig het beheer van meerdere statische websites. Je kunt eventueel de directories met de plug-ins en de themes gezamenlijk in een directory onderbrengen, door bijvoorbeeld eerst in je homegebied een directory ‘.pelican’ aan te maken en hierin de twee repositories te clonen. Je hoeft alleen maar de paden in je configuratiebestand pelicanconf.py aan te passen. Hiermee hou je je homegebied weer wat schoner.
In dit artikel hebben we een introductie van Pelican gegeven. Pelican biedt echter nog véél meer. Mochten we je belangstelling hebben gewekt, dan valt genoeg te ontdekken!
