staticook : générateur de site statique
staticook est un générateur de site statique écrit en C qui va convertir les articles écrits en markdown en HTML et les insérer entre des modèles (templates).
La bibliothèque cmark est utilisée pour la conversion.
Il a été développé sous OpenBSD de façon à pouvoir profiter de pledge, unveil, strlcat...
Il doit pouvoir fonctionner sur d'autres systèmes UNIX avec quelques ajustements mineurs (en allant piocher strlcat par exemple).
TL;DR
pkg_add cmark ftp https://si3t.ch/code/staticook.tgz tar xvzf staticook.tgz cd staticook make cp -r example.tld mysite.tld vi mysite.tld/*.tld vi mysite.tld/staticook.cfg # ajouter des pages dans mysite.tld/site/ staticook mysite.tld
Mise en place
On installe la bibliothèque cmark puis on récupère staticook :
pkg_add cmark ftp https://si3t.ch/code/staticook.tgz tar xvzf staticook.tgz
On compile une première fois pour être sûr que tout va bien :
cd staticook make
Vous pouvez maintenant commencer à travailler sur votre/vos sites. Un exemple est fourni pour vous guider. Voici la procédure à suivre:
1. Créez un dossier qui contiendra votre projet : mkdir projet.tld
2. Copiez dans ce dossier les modèles : cp example.tld/*.tpl projet.tld/
3. Copiez et éditez le fichier de configuration pour votre projet:
cp example.tld/staticook.cfg projet.tld/
4. Créez dans ce dossier un dossier site qui contiendra vos pages en markdown, les images,... :
mkdir projet.tld/site
Désormais, pouvez générer votre site :
staticook projet.tld
Que fait staticook?
- staticook va convertir les fichiers markdown en HTML puis les insérer dans les modèles.
- Il crée un menu de navigation automatiquement mis à jour si une page est créée ou modifiée (pas si elle est supprimée).
- Il crée une page d'archive permettant de chercher parmi toutes les pages de votre site.
- Il crée un fichier /sitemap.xml.
- Il crée un flux ATOM .feed.atom.
Configuration
staticook.cfg
Le principal élément de configuration est le fichier staticook.cfg à déposer dans le dossier de votre projet juste à côté du dossier site. Les lignes commenàçant par "#" sont ignorées. Voici les éléments à définir :
# variables qui seront remplacées dans les modèles AUTHOR = batman EMAIL = foo@bar.org KEYWORDS = key1, key2, key3 URL = https://website.tld SITETITLE = My amazing websize SUBTITLE = Stuff and things LANG = en # dossiers et pages à ignorer dans les menus et archives ignore = /fonts /css /index.html # Chemin vers les modèles depuis le dossier site headertpl = ../header.tpl footertpl = ../footer.tpl archivehead = ../archivehead.tpl archivefoot = ../footer.tpl
Vous remarquerez que les modèles sont à accéder depuis le dossier site. C'est un détail important qui vient du fait que staticook profite d'unveil.
config.h
Quelques points peuvent être configurés en éditant le fichier config.h puis en recompilant staticook. La plupart des éléments n'auront pas à être modifiés dans la majeure partie des cas. Vous pourrez modifier extension par défaut, quelques chemins (notamment le nom du dossier site et le template du flux ATOM.
Modèles (templates)
Les modèles sont de simples fichiers textes pour mettre en forme vos pages. Vous pouvez à n'importe quel endroit, et autant de fois que vous voulez y mettre des variables qui seront remplacées par staticook. Ces dernières doivent être entourées par le texte défini dans le config.h par la variable tpldelim. Par défaut, c'est un "%".
Par exemple, une variable sera écrite ainsi:
Écrit par %AUTHOR% avec joie.
Si dans le fichier staticook.cfg vous avez indiqué
AUTHOR = batman
alors ça deviendra:
Écrit par batman avec joie.
Les variables suivantes sont utilisées :
- AUTHOR: l'auteur du site
- EMAIL: l'email de l'auteur
- KEYWORDS: les mots clés pour l'entête
- URL: URL du site
- SITETITLE: titre du site
- SUBTITLE: sous-titre du site
- LANG: la langue écrite sur le site
- PAGETITLE: le titre d'une page. C'est le premier header "" qui est utilisé ou bien la première ligne avec un "#" dans les sources markdown.
- TAGS: les dossiers dans lesquels une page est déposée constituent ses tags. Cela impose une organisation réfléchie de son site.
- NAVLINKS: liens de navigation vers les pages et dossier à côté de la page courante.
Dans le flux ATOM:
- UPDATED: quand le flux est mis à jour
- PAGEPATH: chemin vers une page
- PAGEUPDATED: quand la page a été mise à jour
- DESCRIPTION: le premier paragraphe ("") d'une page constitue sa description.
CSS
staticook ajoute quelques classes CSS que vous voudrez peut-être configurer dans une feuille de style. Ce sont :
- tag: classe pour les tags.
- archiveitem: contient un lien vers une page dans les archives.
- archivetitle: le titre d'un lien dans les archives.
- archivetags: les tags d'un lien dans les archives.
- dirlink et pagelink: classe des liens dans le menu de navigation respectivement pour un dossier ou une simple page.
De même quelques id sont définies:
- archivelist : la liste des liens dans les archives.
tags
Les tags sont simplement les dossiers contenant les pages. Par exemple, une page /Blog/humeur/grrr.md aura les tags "Blog" et "humeur". Ça impose de bien réfléchir à la structure de son site.
FAQ
Comment uploader mon site ?
Par exemple avec rsync via ssh:
rsync -e "ssh" --exclude="*.md" batman@host.tld:/var/www/htdocs/site
Comment prévisualiser mon site?
cd website/ python -m http.server
Puis ouvrez un navigateur à l'adresse "http://127.0.0.1:8000".
Comment remettre mon site à zéro ?
Supprimez le fichier staticook.recent à côté du dossier site.
Pourquoi des "%"?
unveil, pledge
staticook est "unveiled" dans le dossier qu'il traite. Il ne peut rien voir d'autre du système, ce qui peut être rassurant si on veut mettre en place une ferme de sites.
Il profite aussi de pledge avec les promesses suivantes : "stdio cpath rpath wpath", ceci afin de pouvoir lire les fichiers markdown et en écrire de nouveaux.
Y a-t-il des bugs?
C'est possible. Merci de m'en faire part :).
Comment staticook repère les nouvelles pages?
Il se fie à la date de dernière modification.
Comment obtenir un sitemap.gz ?
gzip --best -c "website/sitemap.xml" > "website/sitemap.gz"
Pourquoi cmark ?
C'est une bibliothèque qui applique le standard commonmark. Elle est facile à utiliser. J'aurais voulu utiliser lowdown, mais cette dernière est loin de ne produire que du HTML et ne rendait pas toujours correctement le markdown donc j'ai pour l'instant mis cette idée en pause.