hscc

Soure code of <https://hugo.soucy.cc>.
git clone git://soucy.cc/hscc.git
Log | Files | Refs

commit 6c55cf9683f0f483370cb8a5947c8bdef32f2e05
parent e5faaa91774c7d70a77a10d2e30dcf3a20e20677
Author: Hugo Soucy <hugo@soucy.cc>
Date:   Wed, 15 Mar 2023 09:55:57 -0400

Remove content

Diffstat:
Mcontent/satelito.md | 262+++----------------------------------------------------------------------------
1 file changed, 8 insertions(+), 254 deletions(-)

diff --git a/content/satelito.md b/content/satelito.md @@ -1,264 +1,18 @@ # 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 +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. - -<!-- Mettre les features ici --> - -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. - -<!-- Et utilise des fichiers lua --> -<!-- script pour les métadonnées. Il n'y a pas de support pour des --> -<!-- métadonnées directement en markdown (*front matter*). Nous comptons --> -<!-- plutôt sur la flexibilité des tableaux lua qui nous permmettent --> -<!-- d'étendre facilement les fonctionnalités des pages. --> - -Pour les gabarits, Satelito utilise l'engin [etlua templating -language](https://github.com/leafo/etlua) 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](https://learnxinyminutes.com/docs/fr-fr/lua-fr/ -"Apprendre X en Y minutes, où X=Lua"). - -## Installation - -Pour installer Satelito, vous devez déjà avoir -[Luarocks](https://luarocks.org/) et [Git](https://git-scm.com/) 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](https://soucy.cc/git/satelito-sample/files.html) 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` - -<!-- The `paths` subtable tells Satelito where are content, templates and --> -<!-- the public_html folders: --> - - paths = { - content = 'content/', - templates = 'templates/', - public_html = 'public_html/', - } - -<!-- And the `mimetypes` subtable determine what kind of assets will be --> -<!-- export in your website tree: --> - - 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 +La documentation est disponible sur codeberg.org. - return - end - } +## Principes de conception -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](https://devdocs.io/lua~5.3/index#3.4.7)). +* fournir des mécanismes souples pour faire des sites web statiques les plus complets possibles +* le moins de dépendances possible +* rapité de compilation +* pas de système de thème +* pas de métadonnées dans les fichiers markdown <!-- la séparation entre le contenu et les métadonnées, permet d'ajouter d'autre langage de balisage léger comme ASCIIDoc ou BBCode ou Textile ou Gemtext -->