rendez-vous sur ArraKISS
Archives ContactATOM
whoami@ybad.name
# find . -iname

    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://dev.ybad.name/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://dev.ybad.name/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?

    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 :

    Dans le flux ATOM:

    CSS

    staticook ajoute quelques classes CSS que vous voudrez peut-être configurer dans une feuille de style. Ce sont :

    De même quelques id sont définies:

    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 “%”?

    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.

    Voir aussi