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

pledge ^🌐

unveil ^🌐

strlcat ^🌐

Il doit pouvoir fonctionner sur d'autres systèmes UNIX avec quelques ajustements mineurs (en allant piocher strlcat par exemple).

strlcat.c ^🌐

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.

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.

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 "%"?

Parce que, et pourquoi pas? ^🌐

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.

lowdown ^🌐