hscc

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

satelito.md (9665B)


      1 # Satelito, est un générateur de site statique
      2 
      3 (*Attention Satelito est en cours de développement ainsi que sa documentation*.)
      4 
      5 (**Ce texte est un brouillon en cours de rédaction**.)
      6 
      7 **Satelito est un générateur de site statique** (SSG) en ligne de
      8 commande, fait avec le langage de programmation **lua** et destiné aux
      9 systèmes d'exploitations dérivés de Unix (GNU/Linux, BSD, Mac OS,
     10 etc). Le support pour Windows viendra peut-être éventuellement.
     11 
     12 **Fonctionnalités:**
     13 
     14 * Faire un site statique HTML à partir de fichiers **markdown** (ou **HTML**).
     15 * Satelito peut générer aussi des pages individuellement ou par
     16   répertoire.
     17 * Créer automatiquement des listes de sous-pages, pour pour toutes les
     18   pages d'index.
     19 * Concevoir des **collections** à partir de nom de répertoire, ou de
     20   nom de page.
     21 * Crée automatiquement des fichiers de syndication **Atom** / RSS, pour
     22   toutes les pages d'index.
     23 * **Rapide**, un site avec des centaines de pages peut être généré en
     24   quelques secondes.
     25 * **Bidouillable** grâce au lua script qui, peut être utilisé
     26   directement dans les gabarits ou les fichiers de configuration.
     27 * Création automatisée d'un fichier **sitemap.xml**.
     28 * Etc.
     29 
     30 <!-- Mettre les features ici -->
     31 
     32 Comme la plupart des SSG (Static Site Generator), Satelito crée des
     33 pages HTML à partir de fichiers markdown (ou HTML). Le site et les
     34 pages page sont configurés à partir de fichier lua. Contrairement à
     35 d'autres SSG, Satelito n'utilise pas de configuration YAML (front
     36 matter) directement dans le markdown ...
     37 
     38 * Cela permet aussi le HTML comme format d'entrée
     39 * En plus de laisser la porte ouverte pour l'intégration éventuelle de
     40   d'autres langages de balisage.
     41 
     42 <!-- Et utilise des fichiers lua -->
     43 <!-- script pour les métadonnées. Il n'y a pas de support pour des -->
     44 <!-- métadonnées directement en markdown (*front matter*). Nous comptons -->
     45 <!-- plutôt sur la flexibilité des tableaux lua qui nous permmettent -->
     46 <!-- d'étendre facilement les fonctionnalités des pages. -->
     47 
     48 Pour les gabarits, Satelito utilise l'engin [etlua templating
     49 language](https://github.com/leafo/etlua) qui est simple mais
     50 puissant, puisqu'il nous permet d'utilisé lua directement dans les
     51 *templates*.
     52 
     53 Ainsi, grâce à l'utilisation de Satelito, vous vous familiarisez avec
     54 langage de programmation, qui a une exécution rapide et [une courte
     55 courbe
     56 d'apprentissage](https://learnxinyminutes.com/docs/fr-fr/lua-fr/
     57 "Apprendre X en Y minutes, où X=Lua").
     58 
     59 ## Installation
     60 
     61 Pour installer Satelito, vous devez déjà avoir
     62 [Luarocks](https://luarocks.org/) et [Git](https://git-scm.com/) sur
     63 votre ordinateur.
     64 
     65 Puis ensuite dans votre terminal:
     66 
     67     luarocks install --server=https://luarocks.org/dev satelito --local.
     68 
     69 Pour tester si votre installtion c'est vraiment bien passée, vous pouvez invoquer la page d'aide avec la commande suivante:
     70 
     71     satelito -h
     72 
     73 Ce qui vous retournera quelque chose qui ressemble à ça:
     74 
     75     Usage: satelito [-h] <command> ...
     76 
     77     Satelito is a static site generator in lua script.
     78 
     79     Options:
     80        -h, --help            Show this help message and exit.
     81 
     82     Commands:
     83        init                  Init the sample website in your $HOME folder.
     84        pipe                  Build the site by inputing one or more markdown files through the pipeline.
     85        make                  Build the site from his directory.
     86 
     87     For more info, see https://soucy.cc/git/satelito/file/README.md.html
     88 
     89 
     90 ### Help ###
     91 
     92 Pour obtenir de l'aide à propos d'une commande en particulier, il faut
     93 taper le nom de la commande, suivie de l'étiquette `-h` ou `--help`:
     94 
     95     satelito pipe --help
     96 
     97 Ainsi on obtient la liste des options liés à la commande.
     98 
     99 ## Démarrer un projet
    100 
    101 Pour créer un projet vous devez utiliser la commande `init` comme suit:
    102 
    103     satelito init
    104 
    105 Satelito clonera alors [le site web de
    106 démonstration](https://soucy.cc/git/satelito-sample/files.html) dans
    107 votre répertoire utilisateur, communément appelé votre `$HOME`.
    108 
    109     Clonage dans '/home/hs0ucy/satelito-sample'...
    110     remote: Enumerating objects: 57, done.
    111     remote: Counting objects: 100% (57/57), done.
    112     remote: Compressing objects: 100% (56/56), done.
    113     remote: Total 57 (delta 14), reused 0 (delta 0), pack-reused 0
    114     Réception d'objets: 100% (57/57), 487.31 Kio | 2.13 Mio/s, fait.
    115     Résolution des deltas: 100% (14/14), fait.
    116     --------------------------------------------------------------------------------------------
    117     total 48
    118     drwxr-xr-x   5 hs  hs   512 Apr  9 15:48 .
    119     drwxr-xr-x  33 hs  hs  1536 Apr  9 15:48 ..
    120     -rw-r--r--   1 hs  hs   922 Apr  9 15:48 config.lua
    121     drwxr-xr-x   3 hs  hs   512 Apr  9 15:48 content
    122     drwxr-xr-x   4 hs  hs   512 Apr  9 15:48 public_html
    123     drwxr-xr-x   2 hs  hs   512 Apr  9 15:48 templates
    124     --------------------------------------------------------------------------------------------
    125     You shoul rename `~/satelito-sample` and edit `~/satelito-sample/config.lua` according to your needs.
    126     --------------------------------------------------------------------------------------------
    127 
    128 À partir de là, je vous conseille de renommer `~/satelito-sample` et
    129 modifier `~/sample/config.lua` selon vos besoins.
    130 
    131 ### Make ###
    132 
    133 Pour construire le site et l'exporter, vous devez aller dans le
    134 répertoire où se trouve le fichier `config.lua` et faire la commande:
    135 
    136     $ satelito make --export
    137 
    138 ## Explorer les concepts de base et certaines conventions
    139 
    140 ### Pipe ###
    141 
    142 Je crois que Satelito est designer davantage comme un générateur de
    143 page que comme un générateur de site, puisqu'il est possible, grâce à
    144 la commande `pipe` de construire une page à la fois ou de cibler un
    145 répertoire en particulier sans devoir tout reconstruire le site.
    146 
    147 Comme par exemple ici, je peux construire une page HTML à partir du
    148 fichier `the-eclipse.md`. Le résultat s'affichera dans le terminal,
    149 pour l'exporter il faut ajouter l'étiquette `--export` (ou `-e`):
    150 
    151     $ echo ~/satelito-sample/content/filmography/the-eclipse.md | satelito pipe
    152 
    153 Ou je peux créer toutes les pages du répertoire `filmography/`:
    154 
    155     $ find ~/satelito-sample/content/filmography/ | satelito pipe
    156 
    157 La commande `pipe` ajoute de la maniabilité à Satelito, puisque cela
    158 vous permet de le combiner avec d'autres programmes de la boîte à
    159 outils Unix:
    160 
    161     $ echo ~/satelito-sample/content/filmography/the-eclipse.md | satelito pipe > ~/test.html
    162 
    163 **Toutefois, la commande `pipe` ne fonctionnera pas avec les fichiers
    164 d'index (`index.md` ou `index.html`) passés directement. C'est une
    165 limitation que je dois corriger éventuellement**.
    166 
    167 ### Le fichier de configuration d'un site
    168 
    169 Le fichier `config.lua` est la pierre angulaire par laquelle Satelito
    170 va générer un site. Il est éditable et on peut y ajouter des
    171 métadonnées de nature plus globale. Ce fichier doit être à la racine
    172 du répertoire.
    173 
    174 Les valeurs suivantes sont essentielles à Satelito:
    175 
    176 * `siteurl`
    177 * `language`
    178 * `paths.content`
    179 * `paths.templates`
    180 * `paths.public_html`
    181 * `mimetypes`
    182 
    183 <!-- The `paths` subtable tells Satelito where are content, templates and -->
    184 <!-- the public_html folders: -->
    185 
    186     paths = {
    187         content = 'content/',
    188         templates = 'templates/',
    189         public_html = 'public_html/',
    190     }
    191 
    192 <!-- And the `mimetypes` subtable determine what kind of assets will be -->
    193 <!-- export in your website tree: -->
    194 
    195     mimetypes = {
    196         'image/svg+xml',
    197         'image/gif',
    198         'image/jpeg',
    199         'image/png',
    200         'application/pdf',
    201     }
    202 
    203 
    204 ### La régle de deux
    205 
    206 Comme je l'ai dit plus haut, avec Satelito il n'y pas de possibilité
    207 d'utiliser de *front matter* dans les fichiers markdown. Pour avoir
    208 des métadonnées liées au contenu, un fichier lua portant le même nom
    209 que le fichier markdown doit être créé.
    210 
    211     -rw-r--r-- 1 hs hs 115 Fec 29 15:16 trip-to-the-moon.lua
    212     -rw-r--r-- 1 hs hs 801 Fec 29 15:17 trip-to-the-moon.md
    213 
    214 #### L'anatomie d'un fichier de métadonnées
    215 
    216 Dans sa plus simple expression ce fichier devrait ressembler à ceci:
    217 
    218     return {
    219       date = "2020-09-01",
    220       datetime = "14:49:00",
    221       title = "A Trip to the Moon",
    222     }
    223 
    224 `date`, `datetime` et `title`, sont les seuls champs requis par Satelito.
    225 
    226 Cependant, aucune erreur ne sera retourner si un fichier de contenu
    227 markdown n'a pas son équivalent en lua. Un fichier HTML sera tout de
    228 même créé, avec comme titre le nom du fichier, et la date et l'heure
    229 courante.
    230 
    231 Dans ces fichiers, on peut ajouter tout ce qui peut aller dans une
    232 table lua et qui sera utile dans les *templates*. Comme par exemple,
    233 dans mes pages, j'ajoute un champs qui contient une liste de mots
    234 clés:
    235 
    236     return {
    237       title = "Satelito, est un générateur de site HTML statique écrit en lua script",
    238       date = "2021-04-09",
    239       datetime = "14:34:50",
    240       keywords = { "lua","ssg","cli","webdev","projet"  }
    241     }
    242 
    243 Il est même possible d'ajouter des fonctions pour manipuler les
    244 données qui sont retourner par l'API:
    245 
    246     return {
    247       date = "2017-03-16",
    248       datetime = "10:00:00",
    249       posttype = "default-index",
    250       title = "Filmography",
    251       get_list_length = function(list)
    252         if type(list) == 'table' then
    253           return #list
    254         end
    255 
    256         return
    257       end
    258     }
    259 
    260 Ici, la fonction `get_list_length` nous retourne le nombre d'élément
    261 que contient l'argument `list`, si ce dernier est un tableau (voir le
    262 [length operator](https://devdocs.io/lua~5.3/index#3.4.7)).
    263 
    264 <!-- 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 -->