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:
- Faire un site statique HTML à partir de fichiers markdown (ou HTML).
- Satelito peut générer aussi des pages individuellement ou par répertoire.
- Créer automatiquement des listes de sous-pages, pour pour toutes les pages d'index.
- Concevoir des collections à partir de nom de répertoire, ou de nom de page.
- Crée automatiquement des fichiers de syndication Atom / RSS, pour toutes les pages d'index.
- Rapide, un site avec des centaines de pages peut être généré en quelques secondes.
- Bidouillable grâce au lua script qui, peut être utilisé directement dans les gabarits ou les fichiers de configuration.
- Création automatisée d'un fichier sitemap.xml.
- Etc.
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 …
- Cela permet aussi le HTML comme format d'entrée
- En plus de laisser la porte ouverte pour l'intégration éventuelle de d'autres langages de balisage.
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:
siteurl
language
paths.content
paths.templates
paths.public_html
mimetypes
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).