Contribution aux connaissances sur le Notebook
template ateliers Journées GT Notebook
Bienvenue!
Bienvenue sur la page de l’atelier Contribution aux connaissances sur le Notebook !
Vous êtes invités à participer à l’édition de cette page. Il suffit
d’ouvrir sa source en cliquant sur le lien edit on hackmd
en haut à gauche de la page :

Pour rafraichir cette page, cliquer sur le bouton
[Refresh] en haut à gauche de la page
Pour en savoir plus, consulter la documentation.
L’atelier
Organisation : Sébastien Rey-Coyrehourcq & membres du GTs.
Objectif·s : Comme indiqué dans la présentation des ateliers, les objectifs de ces deux ateliers sont multiples.
Vous pouvez vous rapporter aux différents objectifs directement dans la partie sous groupe.
Durée : 4h (2*2h)
Méthodes : L’atelier repose sur le principe de …
Outils & librairies : Libres …
Dépots git :
Les notes de la BDC :
https://gitlab.huma-num.fr/gt-notebook/wiki
Le groupe gitlab des dépôts pour l’atelier
https://gitlab.huma-num.fr/gt-notebook/workshop/je_notebook_2024/atelier-bdc-notebooks
Le moteur de la BDC :
https://gitlab.huma-num.fr/gt-notebook/workshop/je_notebook_2024/atelier-bdc-notebooks/fork-mkdocs-zettelkasten
La base Zotero :
https://www.zotero.org/groups/4416056/gt-notebooks/library
Déroulé de l’atelier
Cette section liste les étapes de l’atelier et indique les ressources nécessaires/disponibles pour chaque étape.
Sous groupes pour les Ateliers
:pencil2: Plutôt structure et écriture de textes FR/EN
:keyboard: Plutôt structure et écriture de codes sources
SSGROUPE 1 ( :pencil2: ) Contribution à “Wikipedia” et amélioration de la base bibliographique Zotero du GT :
Objectifs :
Dans ce sous-groupe il s’agit d’initier et de structurer un travail d’écriture qui au delà de la JE. L’actuel page Wikipédia FR sur les Notebooks est courte et peu qualitative. L’objectif à terme est d’améliorer peu à peu le contenu de cette page, ce qui peut aussi nous amener à modifier d’autres pages liés à cette dernière (ex Programmation Lettré, etc.)
Le fait que nous travaillions sur Wikipédia nous amène également à retravailler la structure et le contenu de notre base bibliographique du GT. Sur ce point Raphaëlle, Manon, Sébastien peuvent être consulté pour comprendre la structure actuelle.
Quelques idées d’étapes :
- Déclaré notre intention sur Wikipédia, en suivant le procole et les
guides actuels
- Désigner qui tiendra la plume pour proposer les modifications sur
Wikipedia au nom du collectif GT
- Etablir un plan détaillé de la future page
- Améliorer la base de référence bibliographique dont une partie sera
dédiée à cette page Wikipedia et l’autre partie à la BDC
- Répartir les tâches d’écriture, définir un calendrier de réunions
SSGROUPE 2 ( :pencil2: ) Contribution au contenu la BDC du GT Notebook et amélioration de la base bibliographique Zotero du GT :
Objectifs :
Dans ce sous-groupe il s’agit d’initier et de structurer un travail d’écriture qui au delà de la JE. Notre première tentative de PKM lancé en 2021 n’a pas eu le succès escompté, y compris auprès des membres motivés.
Après plusieurs discussions au sein d’un sous groupe dédié du GT, nous avons identifié plusieurs freins, dont le premier tient probablement de la pléthore et de la diversité d’outils que nous utilisons déjà tous au jour le jour : emacs, vi, mails, etc. Il faut donc que l’édition de cette BDC s’intègre au mieux dans nos workflows quotidien, y compris au sein du GT, sous peine d’être voué à l’échec. Ce volet là renvoie plutôt au SSGROUPE 3 “Code & outils collectifs/collaboratifs”
Une autre cause est probablement l’absence d’un plan de route plus précis pour le contenu et la structuration de cette PKM.
Quelques idées d’étapes :
- Etablir des templates d’écriture selon les connaissances à intégrer dans la base
- Etablir une liste d’axiome important, des noeuds plus important de part la densité des liens qu’ils ont avec les autres noeuds (ex Literate Programming)
- Documenter le protocole à suivre (tags/catégories, nomages des fichiers, etc.) pour un ajout de document à la base Zotero
- Verser les comptes-rendu des deux années passés dans la BDC pour sortir peu à peu le travail de HackMD.
- réintégrer les tags dans les md avec la syntaxe proposé par le template mkdocs zettelkasten, pour le moment çà ne marche pas.
SSGROUPE 3 (:keyboard:) : Contribuer à la fabrique de la BDC
Objectifs :
En 2021, nous avions déployé une première base de connaissance, reprenant un format zettelkasten. L’idée c’était que chacun.e puis ajouter de la connaissance pour capitaliser en un seul endroit nos réflexions et notre veille autour des Notebooks. Cette base devait être reproductible, comme le reste de l’atelier en 2021.
A cette époque j’avais fait le choix de packager les différentes parties avec Nix sous la forme de Flakes.
Comme indiqué dans le précédent SSGROUPE 2, il y avait trop de frein à l’utilisation. Après plusieurs discussions au sein d’un sous groupe dédié du GT, nous avons identifié plusieurs freins, dont le premier tient probablement de la pléthore et de la diversité d’outils que nous utilisons déjà tous au jour le jour : emacs, vi, mails, etc. Il faut donc que l’édition de cette BDC s’intègre au mieux dans nos workflows du quotidien, y compris au sein du GT, sous peine d’être voué à l’échec.
Deux idée importante :
- avoir une base de markdown centrale, lisible et si possible
éditable sans conflit (ex wikilink pareil partout) avec
n’importe quel outil moyennant qu’on respecte un frontmatter simple (ID,
tags, etc)
- couplage avec un outil qui permet un double usage synchrone et
asynchrone du contenu de la BDC (type hackmd via l’API,
etherpad, Stylo)
Quelques idées d’amélioration ou de correction :
- ajout d’un graph de navigation entre les noeuds de la BDC (ex : https://hugocisneros.com/notes/, https://quartz.jzhao.xyz/) => Sigma.js ?
- ajout d’un bouton edit aux pages, couplage système asynchrone (git) avec un outil d’écriture synchrone (hackmd, stylo, etc.) => pas évident, on a fait un peu de veille… mais si on peut se raccrocher à stylo ca serait intéressant car communauté FR.
- tester que les fichiers générés par différents IDE courant pour l’édition de base de connaissance en markdown (emacs, vim, obsidian, logseq, etc.) sont bien gérés au niveau du frontmatter, sinon envisager des scripts de pre-traitement/post-traitement ?
- déployer le site web généré de la BDC avec le CI Gitlab, avec Guix
Prise de note
Cette section peut être utilisée librement comme espace d’organisation et de documentation pendant l’atelier.
Participants : ajoutez vos noms ici
SS Groupe 3 Améliorer le
Ancien moteur BDC et packaging NIX :
- Le générateur de site statique SlipBox amélioré pour l’occasion : https://gitlab.huma-num.fr/gt-notebook/nix/wiki-script
- Une version de Pandoc plus à jour que celle de Nix : https://gitlab.huma-num.fr/gt-notebook/nix/pandoc-2-14-02
- La mise en lien des deux packages précédents : https://gitlab.huma-num.fr/gt-notebook/nix/wiki-pandoc-nix
Nouveau moteur BDC et packaging Guix
Description de l’architecture
Le premier dépôt contient l’ensemble des dépendances packagés sous forme de modules pour compiler la BDC avec GUIX. Ces dépendances sont regroupés dans un channel guix qui peut être partagé avec d’autres utilisateurs ayant besoin de ces dépendances.
Le deuxième dépôt est un clone/fork du template et plugin MKDocs Zettelkasten.
Le troisième dépôt contient la définition de notre site de documentation (
mkdocs.yml), utilisant le template MKDocs Zettelkasten comme theme/plugin.Dans ce troisième dépôt la BDC est définie comme un submodule git. Après clone du troisième dépot, le copie (liée) du dépôt qui contient les notes est dans le répertoire
/docs.
Normalement vous n’avez pas besoin de toucher au premier dépôt sauf si vous ajouter une dépendance, ou une version de dépendance qui ne serais pas déjà packagé dans Guix.
Le deuxième dépôt contenant le thème/plugin Zettelkasten est celui que l’on modifiera lorsque l’on voudra ajouter des fonctionnalités au thème.
Le troisième dépôt s’appuie le plugin/thème tel qu’il est
construit/tuné dans le deuxième dépôt. A ce dernier s’ajoute d’autres
plugin de MkDocs :
- La reconnaissance de la bibliographie via un bibtex dans les fichiers
.md est ajouté par le plugin mkdocs-bibtex
- La récupération de la base bibtex depuis zotero se fait avant
compilation du site (grâce au plugin mkdocs-gen-files), via
le fichier /scripts/retrieve-bib.py.
C’est aussi dans ce troisième dépôt qu’est fait le lien avec la BDC,
au travers d’un submodule qui point sur un commit du dépot
. Il faut intervenir manuellement pour mettre à jour ce commit en cas
d’update des notes dans la BDC. Le protocole standard est
cd /docs ; git pull ; cd .. ; git add /docs; git commit -m "update submodule ; git push
Installation avec Guix
- Installer Guix sous votre Linux (ex :
apt-get install guix) - Cloner le premier dépôt contenant le channel (dépendance)
- Cloner le troisième
dépot qui contient le moteur et un lien versla BDC :
git clone --recurse-submodules https://gitlab.huma-num.fr/gt-notebook/workshop/je_notebook_2024/atelier-bdc-notebooks/wiki-under-mkdocs - modifier le fichier
channel.scmdu troisième dépot et remplacer l’url actuelle par l’urlfile://actuelle du channel tel que cloné sur votre disque, puis enregistrez. - Executer la commande dans le répertoire :
guix time-machine -C channels.scm -- shell -m manifest.scm python touch notebooks.bibpour la création d’un fichier vide accueillant la biblio- Executez dans votre shell les deux commandes suivantes, nécessaire pour récupérer pour les fichiers bibtex de la base zotero :
export GROUP_ID=4416056
export ZOTERO_KEY=06FLQnd18f1L4v6lwjefu4Pc
- Enfin, tapez la commande
mkdocs build -f mkdocs.ymlpuismkdocs serve
Installation sans Guix
- Cloner le deuxième dépot qui contient le fork modifié du plugin/template mkdocs.
- Installer un gestionnaire spécifique qui permet d’installer plusieurs version de python sous un même système : pyenv ou asdf par exemple.
- Installer python 3.8 (ex avec pyenv install 3.8)
- Installer pipenv avec votre packageur systeme : apt-get install python3-pipenv
- Dans le répertoire du projet, lancez
make updatece qui normalement devrait trouver python 3.8 et installer les dépendances requises
- pipenv shell lance un environnement avec les dépendances installées
- Cloner le troisieme
dépot qui contient le moteur et le submodule git vers la BDC :
git clone --recurse-submodules https://gitlab.huma-num.fr/gt-notebook/workshop/je_notebook_2024/atelier-bdc-notebooks/wiki-under-mkdocs - A ce stade il faut aussi installer les nouveaux plugins /dépendances
listées dans mkdocs.yml suite aux modifications que j’ai faite
dans le fork :
pip install mkdocs-gen-filespour lancer des scripts avant la génération du sitepip install mkdocs-bibtexpour la gestion de la biblio (voir/scripts)pip install pyzoteropour la gestion de la biblio (voir/scripts)touch notebooks.bibpour la création d’un fichier vide accueillant la biblio- Executez dans votre shell les deux commandes suivantes, nécessaire pour récupérer pour les fichiers bibtex de la base zotero :
export GROUP_ID=4416056
export ZOTERO_KEY=06FLQnd18f1L4v6lwjefu4Pc
- Enfin, tapez la commande
mkdocs build -f mkdocs.ymlpuismkdocs serve
Compte-rendu
Cette section est utilisée comme espace de consolidation : synthèse des réalisation, difficultés/freins rencontré·e·s, pistes pour la suite, autre…