wiki

Wiki for sbi.re
Log | Files | Refs | Submodules | README

wiki.md (2490B)


1---
2title: Wiki
3author: flupe
4updated: 08/11/2021
5---
6
7Le wiki des sbires est généré statiquement à l'aide d'un utilitaire fait
8maison. Le code source du générateur et l'intégralité du contenu sont hébergés
9dans le dépot public [git.sbi.re/wiki](https://git.sbi.re/wiki).
10
11## Edition du wiki
12
13Pour éditer le contenu du wiki, il suffit de cloner le dépot, modifier
14localement, puis push sur le serveur --- à condition d'avoir les permissions
15d'édition.
16
17    $ git clone git@sbi.re:wiki
18    $ cd git
19    ...
20    $ git commit -m "wiki update"
21    $ git push origin master
22
23Le wiki sera généré sur le serveur automatiquement.
24
25## Génération du wiki
26
27Le générateur du wiki est codé en Haskell et utilise la libraire `achille`.
28Pour pouvoir générer le wiki en local --- et donc voir à quoi ressemblent nos
29modifications sans faire travailler le serveur --- il faut compiler le
30générateur.
31
32    $ cabal install --overwrite-policy=always
33    $ wiki build
34
35Le générateur est *incrémental*, regénérer le wiki après avoir édité le
36contenu est donc a priori très rapide™.
37
38## Astuces
39
40### Bandeau d'information
41
42Pour afficher un bandeau informatif sur la page d'accueil --- en cas de
43maintenance par exemple --- il suffit de modifier `content/index.md` pour
44ajouter une valeur dans le champ `info` des métadonnées :
45
46
47```md
48---
49projects:
50  - ...
51info: |
52  Le serveur est en cours de réinstallation, certaines pages
53  ne sont peut-être plus d'actualité.
54---
55...
56```
57
58Après regénération, le bandeau apparaît. Il suffit de supprimer ce champ du
59fichier pour le faire disparaître à nouveau. Il est de bon ton de préfixer le
60message d'une date.
61
62### Liens internes
63
64Pour l'instant le wiki est assez sommaire. A terme, et une fois qu'il sera un
65peu plus étoffé, on aimerait appliquer une méthodologie proche de *Zettelkasten*.
66Pour insérer un lien vers une autre page du wiki, ne pas utiliser un lien direct
67`https://sbi.re/wiki/...` mais préférer le format `wiki:...`.
68Le chemin d'un fichier est considéré comme son *UID* ou *identifiant unique*.
69Par exemple, l'*UID* de la page que vous êtes en train de lire est `meta/wiki`.
70
71Pour ajouter un lien vers cette page d'ailleurs sur le wiki, on fait donc ainsi
72:
73
74```md
75Pour en apprendre plus, suivre ce [lien](wiki:meta/wiki)
76```
77
78A l'avenir, la syntaxe suivante sera aussi supportée, et ajoutera le titre de la
79page ciblée comme intitulé du lien.
80
81```md
82- [wiki:meta/wiki]
83- [wiki:meta/git]
84```