Un générateur de site statique - retour accueil
git clone git://bebou.netlib.re/catium
Log | Files | Refs | README |
USAGE (13742B)
1 # Comment utiliser Catium
2
3 Ce document existe pour apprendre à utiliser Catium sans pour autant lire
4 toute la documentation se trouvant aujourd'hui dans [cet
5 article](construire.html).
6
7 A noter, Catium est conçu pour être modifiable et même inciter à l'être.
8 Ainsi ce document documente comment utiliser Catium dans sa version
9 "minimale". Des cas de modifications relativement simples seront couverts à la
10 fin de ce document.
11
12 Il ne faut pas s'attendre à pouvoir modifier Catium facilement sans aucune
13 compétence en make/markdown/shell/html. L'idée est de faire de Catium un
14 logiciel favorisant l'apprentissage des ces technologies dont on estime
15 qu'elles constituent un socle de compétences de bases en informatique. On
16 pourrait évidemment débattre de ce que l'on inclu dans ce socle ou pas.
17
18 ## Dépendances
19
20 En l'état Catium nécessite
21
22 * de choisir un ou plusieurs formats dans lesquels écrire le site (du
23 markdown par ex)
24 * un ou plusieurs logiciels qui feront la traduction de ce ou ces formats
25 vers de l'html (cmark/lowdown/pandoc etc)
26 * un interpréteur shell POSIX (sauf bash pour le moment)
27 * GNU Make >3.8 (pour le moment)
28
29 Pour la suite de ce document nous partons du principe que le site est écrit en
30 markdown.
31
32 ## Générer le site
33
34 Catium utilise GNU Make pour orchestrer la génération du site. Les règles de
35 génération sont écrites dans le fichier `makefile`. Pour lancer la génération
36 faire
37
38 make
39
40 Il est possible d'accélérer le processus en parallélisant avec l'option `-j`.
41 Pour purger les fichiers produits faire
42
43 make clean
44
45 Il n'est pas toujours nécessaire de faire un `clean` avant de faire un `make`,
46 les fichiers seront réécrits. La génération du site va transposer les fichiers
47 et l'arborescence source - dans `./contents` - vers la destination - le dossier
48 `./public`. Ainsi avec l'arborescence
49
50 ./contents
51 ├── archives
52 │ └── index.sh
53 ├── articles
54 │ └── youtube
55 │ ├── arguments-to-plumber.patch
56 │ ├── display_author.patch
57 │ └── index.sh
58 ├── index.sh
59 └── notes
60 └── laconvivialite
61 └── index.sh
62
63 `make` génère l'arborescence
64
65 ./public
66 ├── archives
67 │ ├── index.html
68 ├── articles
69 │ └── youtube
70 │ ├── arguments-to-plumber.patch
71 │ ├── display_author.patch
72 │ ├── index.html
73 ├── index.html
74 └── notes
75 └── laconvivialite
76 └─── index.html
77
78 Pour chaque fichier présent dans `./contents` le `makefile` a une règle expliquant à
79 `make` ce qu'il faut faire. Sans rentrer dans les détails, les fichiers `.sh`
80 sont transformés en `.html` et copiés dans une arbo identique recrée sous
81 `./public`.
82
83 ## Créer le contenu
84
85 L'exemple précédant se base sur le contenu du site Katzele mais vous voulez
86 évidemment faire le votre. Imaginons partir de zéro.
87
88 ### Template HTML
89
90 Il nous faut au moins un template HTML qui structurera nos pages. Ce sera
91 l'échaffaudage pour nos pages. Ce template devra se trouver dans le dossier
92 `./layouts/html`.
93
94 Prenons celui-ci comme exemple :
95
96 layout() {
97 <<@@ cat
98 <!DOCTYPE html>
99 <html>
100 <head>
101 <title>${title?La page dont le chemin s'affiche au dessus nécessite un titre}</title>
102 ${STYLE:+<link rel="stylesheet" href=\"$STYLE\" />}
103 <meta charset="utf-8">
104 <meta name="viewport" content="width=device-width,initial-scale=1.0">
105 <meta name="description" content="$description" />
106 <meta name="author" content="$author" />
107 </head>
108 <body>
109 <main>
110 $(show main)
111 </main>
112 </body>
113 </html>
114 @@
115 }
116
117 Les lignes `layout() <<@@ cat` et à la fin `@@` déclarent une fonction shell
118 qui contient un heredoc. Si vous voulez en savoir plus lisez [cet
119 article](construire.html) ou lisez le manuel de dash. Vous pouvez faire
120 abstraction sinon.
121
122 Le contenu qui se trouve entre ces deux lignes est un mélange d'HTML pur, de
123 variables shell et d'expansion de variables shell. Je ne vais pas les
124 expliciter ici. Ce template convient pour générer des pages très simples,
125 sans header ni footer, simplement le corps de la page que l'on écrit en
126 markdown. Si cela vous convient vous pouvez ne pas y toucher. Par défaut la
127 feuille de style qui sera utilisée est `./contents/style.css`. Elle contient le
128 thème de Katzele, vous pouvez la modifier à votre guise.
129
130 Pour d'éventuelles modifications du template ce qu'il faut à minima retenir est
131 que vous pouvez ici ajouter de l'HTML comme bon vous semble et avoir recours à
132 la commande `show nom_de_section` pour ajouter des sections que vous
133 renseignerez en markdown dans vos fichiers sources. Si vous voulez des exemples
134 de modification voir plus loin dans ce document. Pour des exemples de sites
135 aboutis voir [la galerie](/#galerie).
136
137 ### Fichier source markdown
138
139 Les fichiers sources des pages doivent comporter l'extension `.sh` et être
140 exécutables. Ils doivent commencer par la ligne
141
142 #! /usr/bin/env ./page
143
144 pour être préprocessés par le script `page`. Ils doivent ensuite contenir un
145 ensemble de métadonnée. En l'état Catium propose
146
147 * `title: "titre de la page"` pour renseigner le contenu de la balise `<title>`, à
148 savoir ce qui s'affiche dans le titre de l'onglet de votre navigateur
149 * `author: "nom de l'auteurice"` pour suivre qui a rédigé la page. Avec le
150 template présenté auparavant cette donnée ne se retrouvera nul par dans
151 l'HTML. Nous verrons un exemple de modification plus tard pour l'intégrer.
152 * `publication: "date de publication de la page"` pour suivre la date de publication.
153 Elle peut ensuite être réutilisée dans la génération du site. Voir le
154 fichier CONSTRUIRE pour un exemple.
155 * `description: "description du contenu"` pour alimenter la balise meta `description`,
156 à savoir ce qui s'affichera comme contenu dans le résultat des moteurs de
157 recherche par exemple.
158
159 On renseigne ces métadonnées en appelant, dans le fichier sh, les différentes
160 "variables". Par exemple pour une page d'accueil
161
162 title: "Page d'accueil de mon site"
163 author: moi
164 publication: 2023-06-21
165 description: "Site de machin chose, bidule à chouette à truc muche"
166
167 Il faut ensuite écrire le contenu markdown. Pour cela faire appel à
168 l'instruction `section:` marquant le début du markdown. Il faut mettre à la
169 suite de cette instruction la section du template dans laquelle on veut que le
170 contenu qui suive aille. Dans notre exemple de template il n'y a qu'une section
171 (marquée par la commande `$(show main)`) qui remplira bêtement la balise `main`,
172 unique balise du body. C'est le mot clef suivant `show` et non pas le nom de la
173 balise HTML qu'il faut retenir et faire correspondre avec ce que l'on va écrire
174 dans le fichier markdown. Il est naturel que la balise et le nom de la section
175 soient identiques mais cela n'est pas nécessaire. Pour y mettre du contenu nous
176 pouvons donc écrire :
177
178 section: main
179 # Le site de machin chose
180 Salut !
181
182 ## Ma vie mon oeuvre
183
184 J'ai travaillé ici, là-bas et accompli cela
185
186 * premier truc
187 * second truc
188 endsection
189
190 Il faut fermer l'instruction `section:` avec un `endsection`. Au final notre
191 document ressemble à :
192
193 #! /usr/bin/env ./page
194 title: "Page d'accueil de mon site"
195 author: moi
196 publication: 2023-06-21
197 description: "Site de machin chose, bidule à chouette à truc muche"
198 section: main
199 # Le site de machin chose
200 Salut !
201
202 ## Ma vie mon œuvre
203
204 J'ai travaillé ici, là-bas et accompli cela
205
206 * premier truc
207 * second truc
208 endsection
209
210 Si ce fichier se nomme `index.sh` et se trouve à la racine du dossier `./contents`
211 alors exécuter `make` génèrera ce `index.html` dans `./public` :
212
213 <!DOCTYPE html>
214 <html>
215 <head>
216 <title>Page d'accueil de mon site</title>
217 <link rel="stylesheet" href="style.css" />
218 <meta charset="utf-8">
219 <meta name="viewport" content="width=device-width,initial-scale=1.0">
220 <meta name="description" content="Site de machin chose, bidule à chouette à truc muche" />
221 <meta name="author" content="moi" />
222 </head>
223 <body>
224 <main>
225 <h1>Le site de machin chose</h1>
226 <p>Salut !</p>
227 <h2>Ma vie mon oeuvre</h2>
228 <p>J'ai travaillé ici, là-bas et accompli cela</p>
229 <ul>
230 <li>premier truc</li>
231 <li>second truc</li>
232 </ul>
233 </main>
234 </body>
235 </html>
236
237 Dernière astuce, en dehors des blocs `section: nom_de_section ... endsection`
238 vous pouvez exécuter du shell. Ainsi il est possible, avec votre langage
239 préféré, de générer du markdown. Cela peut être pratique quand l'on veut
240 générer quelque chose en fonction d'un contenu qui change souvent et dont on ne
241 connaît pas, à priori, la teneur. Par exemple un plan de site. Pour ce faire
242 écrivez le code que vous souhaitez et pipez le dans la commande `save` suivi
243 du nom de la section dans laquelle vous voulez que le contenu apparaisse.
244 Ainsi, en reprenant la fin du document :
245
246 J'ai travaillé ici, là-bas et accompli cela
247
248 * premier truc
249 * second truc
250 endsection
251
252 echo "[Un autre site cool](lien_vers_site_cool)" | save main
253
254 Ajoutera un lien dans la section main
255
256 <li>premier truc</li>
257 <li>second truc</li>
258 </ul>
259 <p><a href="lien_vers_site_cool">Un autre site cool</a></p>
260 </main>
261 </body>
262 </html>
263
264 Cela peut être pratique pour générer du contenu dynamiquement en fonction
265 d'autres morceaux du site, de la date etc.
266
267 Voilà, à partir de là si vous savez écrire du markdown et que vous n'avez pas
268 besoin d'autre chose que des pages simplistes comme celles générées avec le
269 template fourni vous avez les cartes en main pour créer votre site avec
270 Catium. Cela dit l'esprit de l'outil est qu'il est de nature "hackable" avec
271 des compétences que l'on juge, dans le collectif, comme étant de bonnes
272 candidates pour être des compétences "socles" dans l'informatique.
273
274 En dessous nous voyons quelques cas élémentaires de modifications qui
275 pourraient vous intéresser ou vous mettre sur la bonne piste. Pour des exemples
276 plus aboutis voir [la galerie](/#galerie).
277
278 ## Modifier catium
279
280 Admettons que vous vouliez apporter les modifications suivantes à l'existant :
281
282 * Gestion d'une métadonnée "langue" car le site est bilingue
283 * Ajouter une section au template
284
285 ### Ajouter une métadonnée
286
287 Vous l'avez peut-être remarqué, il existe une balise `<html lang="fr">` dans
288 notre template. Cette balise sert à déclarer la langue du contenu qui suit.
289 Cela permet entre autre aux lecteurs d'écrans de lire correctement le contenu
290 de la page. Si vous tenez un site bilingue vous pourriez vouloir spécifier la
291 langue article par article et non pas de façon figée dans le template.
292
293 Pour cela ajoutons une métadonnée qui nous utiliserons au début des articles.
294 Pour ajouter une métadonnée il nous faut modifier le fichier `page` qui
295 contient le code pour les rendre opérantes. Dans ce fichier, ajouter une
296 métadonnée revient à déclarer un nouvel alias et une fonction correspondante.
297 En ce basant sur ce qui existe pour `title:` :
298
299 alias lang:="lang"
300 lang() lang="$*"
301
302 Dorénavant quand on écrira `lang: fr" dans un fichier, la variable `lang` prendra
303 pour valeur "fr". Il suffit ensuite de l'appeler au bon endroit dans le template
304
305 layout() <<@@ cat
306 <!DOCTYPE html>
307 <html lang="$lang">
308 <head>
309
310 Hop, nous pouvons dorénavant déclarer la langue d'un article. Nous pourrions
311 mettre un petit filet pour nous assurer de ne pas oublier d'un déclarer un :
312
313 <html lang="${lang?Langue de l'article non déclarée}">
314
315 Si la variable est vide (parce que nous aurions oublié de renseigner `lang:` dans
316 un article) alors la génération du site va se terminer et le message d'erreur
317 sera affiché. Alternativement il est possible de choisir une valeur par
318 défaut comme ceci :
319
320 <html lang="${lang:-fr}">
321
322 ### Ajouter une section au template
323
324 Admettons que nous souhaitons ajouter un footer et un aside dont nous voulons
325 maitriser le contenu. Rien de plus simple, il suffit de créer les balises
326 qui vont bien et d'appeler la commande `show` avec les noms des sections.
327
328 layout() <<@@ cat
329 <!DOCTYPE html>
330 <html lang="fr">
331 <head>
332 <meta charset="utf-8">
333 <title>${title?La page dont le chemin s'affiche au dessus nécessite un titre}</title>
334 <meta name="viewport" content="width=device-width,initial-scale=1.0">
335 ${STYLE:+<link rel=\"stylesheet\" href=\"$STYLE\"/>}
336 <meta name="description" content="$description">
337 </head>
338 <body>
339 <main id="main" class="main">
340 $(show main)
341 </main>
342 <aside id="aside" class="aside">
343 $(show aside)
344 </aside>
345 <footer id="footer" class="footer">
346 $(show footer)
347 <p>$author</p>
348 </footer>
349 </body>
350 </html>
351 @@
352
353 Au passage nous mettons le nom de l'auteurice, se trouvant dans la variable
354 `$author` grâce à l'instruction `author:`, dans le footer.
355 Dans les sources d'une page il faudrait ensuite appeler `section:` avec les noms de
356 sections :
357
358 section: main
359 # Titre de l'article
360 blablalba
361 endsection
362
363 section: aside
364 truc que l'on raconte dans l'aside
365 endsection
366
367 section: footer
368 contenu du footer
369 endsection
370
371 A noter, si vous en avez une utilité quelconque, il est possible d'ouvrir et de
372 fermer les `section:` à votre guise. Le contenu d'une section sera généré dans
373 l'ordre d'apparition dans le document mais les sections n'interfèrent pas entre
374 elles.
375
376 Il est donc possible d'écrire :
377
378 section: main
379 # Titre
380 azdazda
381 endsection
382
383 section: footer
384 machin
385 endsection
386
387 section: main
388 bidule
389 endsection
390
391 section: footer
392 truc
393 endsection
394
395 cela reviendrait à écrire
396
397
398 section: main
399 # Titre
400 azdazda
401 machin
402 endsection
403
404 section: footer
405 bidule
406 truc
407 endsection
408
409 Pareil avec les appels à la commande `save nom_de_section` suite à un pipe.