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