Satelito, est un générateur de site statique

(Attention Satelito est en cours de développement ainsi que sa documentation.)

(Ce texte est un brouillon en cours de rédaction.)

Satelito est un générateur de site statique (SSG) en ligne de commande, fait avec le langage de programmation lua et destiné aux systèmes d'exploitations dérivés de Unix (GNU/Linux, BSD, Mac OS, etc). Le support pour Windows viendra peut-être éventuellement.

Fonctionnalités:

Comme la plupart des SSG (Static Site Generator), Satelito crée des pages HTML à partir de fichiers markdown (ou HTML). Le site et les pages page sont configurés à partir de fichier lua. Contrairement à d'autres SSG, Satelito n'utilise pas de configuration YAML (front matter) directement dans le markdown …

Pour les gabarits, Satelito utilise l'engin etlua templating language qui est simple mais puissant, puisqu'il nous permet d'utilisé lua directement dans les templates.

Ainsi, grâce à l'utilisation de Satelito, vous vous familiarisez avec langage de programmation, qui a une exécution rapide et une courte courbe d'apprentissage.

Installation

Pour installer Satelito, vous devez déjà avoir Luarocks et Git sur votre ordinateur.

Puis ensuite dans votre terminal:

luarocks install --server=https://luarocks.org/dev satelito --local.

Pour tester si votre installtion c'est vraiment bien passée, vous pouvez invoquer la page d'aide avec la commande suivante:

satelito -h

Ce qui vous retournera quelque chose qui ressemble à ça:

Usage: satelito [-h] <command> ...

Satelito is a static site generator in lua script.

Options:
   -h, --help            Show this help message and exit.

Commands:
   init                  Init the sample website in your $HOME folder.
   pipe                  Build the site by inputing one or more markdown files through the pipeline.
   make                  Build the site from his directory.

For more info, see https://soucy.cc/git/satelito/file/README.md.html

Help

Pour obtenir de l'aide à propos d'une commande en particulier, il faut taper le nom de la commande, suivie de l'étiquette -h ou --help:

satelito pipe --help

Ainsi on obtient la liste des options liés à la commande.

Démarrer un projet

Pour créer un projet vous devez utiliser la commande init comme suit:

satelito init

Satelito clonera alors le site web de démonstration dans votre répertoire utilisateur, communément appelé votre $HOME.

Clonage dans '/home/hs0ucy/satelito-sample'...
remote: Enumerating objects: 57, done.
remote: Counting objects: 100% (57/57), done.
remote: Compressing objects: 100% (56/56), done.
remote: Total 57 (delta 14), reused 0 (delta 0), pack-reused 0
Réception d'objets: 100% (57/57), 487.31 Kio | 2.13 Mio/s, fait.
Résolution des deltas: 100% (14/14), fait.
--------------------------------------------------------------------------------------------
total 48
drwxr-xr-x   5 hs  hs   512 Apr  9 15:48 .
drwxr-xr-x  33 hs  hs  1536 Apr  9 15:48 ..
-rw-r--r--   1 hs  hs   922 Apr  9 15:48 config.lua
drwxr-xr-x   3 hs  hs   512 Apr  9 15:48 content
drwxr-xr-x   4 hs  hs   512 Apr  9 15:48 public_html
drwxr-xr-x   2 hs  hs   512 Apr  9 15:48 templates
--------------------------------------------------------------------------------------------
You shoul rename `~/satelito-sample` and edit `~/satelito-sample/config.lua` according to your needs.
--------------------------------------------------------------------------------------------

À partir de là, je vous conseille de renommer ~/satelito-sample et modifier ~/sample/config.lua selon vos besoins.

Make

Pour construire le site et l'exporter, vous devez aller dans le répertoire où se trouve le fichier config.lua et faire la commande:

$ satelito make --export

Explorer les concepts de base et certaines conventions

Pipe

Je crois que Satelito est designer davantage comme un générateur de page que comme un générateur de site, puisqu'il est possible, grâce à la commande pipe de construire une page à la fois ou de cibler un répertoire en particulier sans devoir tout reconstruire le site.

Comme par exemple ici, je peux construire une page HTML à partir du fichier the-eclipse.md. Le résultat s'affichera dans le terminal, pour l'exporter il faut ajouter l'étiquette --export (ou -e):

$ echo ~/satelito-sample/content/filmography/the-eclipse.md | satelito pipe

Ou je peux créer toutes les pages du répertoire filmography/:

$ find ~/satelito-sample/content/filmography/ | satelito pipe

La commande pipe ajoute de la maniabilité à Satelito, puisque cela vous permet de le combiner avec d'autres programmes de la boîte à outils Unix:

$ echo ~/satelito-sample/content/filmography/the-eclipse.md | satelito pipe > ~/test.html

Toutefois, la commande pipe ne fonctionnera pas avec les fichiers d'index (index.md ou index.html) passés directement. C'est une limitation que je dois corriger éventuellement.

Le fichier de configuration d'un site

Le fichier config.lua est la pierre angulaire par laquelle Satelito va générer un site. Il est éditable et on peut y ajouter des métadonnées de nature plus globale. Ce fichier doit être à la racine du répertoire.

Les valeurs suivantes sont essentielles à Satelito:

paths = {
    content = 'content/',
    templates = 'templates/',
    public_html = 'public_html/',
}

mimetypes = {
    'image/svg+xml',
    'image/gif',
    'image/jpeg',
    'image/png',
    'application/pdf',
}

La régle de deux

Comme je l'ai dit plus haut, avec Satelito il n'y pas de possibilité d'utiliser de front matter dans les fichiers markdown. Pour avoir des métadonnées liées au contenu, un fichier lua portant le même nom que le fichier markdown doit être créé.

-rw-r--r-- 1 hs hs 115 Fec 29 15:16 trip-to-the-moon.lua
-rw-r--r-- 1 hs hs 801 Fec 29 15:17 trip-to-the-moon.md

L'anatomie d'un fichier de métadonnées

Dans sa plus simple expression ce fichier devrait ressembler à ceci:

return {
  date = "2020-09-01",
  datetime = "14:49:00",
  title = "A Trip to the Moon",
}

date, datetime et title, sont les seuls champs requis par Satelito.

Cependant, aucune erreur ne sera retourner si un fichier de contenu markdown n'a pas son équivalent en lua. Un fichier HTML sera tout de même créé, avec comme titre le nom du fichier, et la date et l'heure courante.

Dans ces fichiers, on peut ajouter tout ce qui peut aller dans une table lua et qui sera utile dans les templates. Comme par exemple, dans mes pages, j'ajoute un champs qui contient une liste de mots clés:

return {
  title = "Satelito, est un générateur de site HTML statique écrit en lua script",
  date = "2021-04-09",
  datetime = "14:34:50",
  keywords = { "lua","ssg","cli","webdev","projet"  }
}

Il est même possible d'ajouter des fonctions pour manipuler les données qui sont retourner par l'API:

return {
  date = "2017-03-16",
  datetime = "10:00:00",
  posttype = "default-index",
  title = "Filmography",
  get_list_length = function(list)
    if type(list) == 'table' then
      return #list
    end

    return
  end
}

Ici, la fonction get_list_length nous retourne le nombre d'élément que contient l'argument list, si ce dernier est un tableau (voir le length operator).