onfeuh

Comment fonctionne ce site

Contexte

Ce site est une collection de notes personnelles synchronisées entre mes appareils et automatiquement publiées sur internet - ce que certaines personnes appellent un digital garden.

Cela fait longtemps que j’essaie de mettre ce type de système en place, mais j’ai eu du mal Ă  trouver une solution qui remplisse mon petit cahier des charges. En ce qui me concerne j’avais besoin de rĂ©unir les conditions suivantes :

Vous verrez que j’ai dĂ» faire quelques concessions, mais voici le système que j’ai mis en place.

Outils utilisés

Je ne suis pas pleinement satisfais par cette liste. J’aimerais hĂ©berger mes notes chez moi. Techniquement, je pourrais auto-hĂ©berger Gitlab, mais cela demande beaucoup de travail et donnerait quelque chose de moins fiable que ce que j’ai dĂ©jĂ  sur la plateforme officielle

Je n’aime pas beaucoup Obsidian et son ecosystème, pour des raisons de licences, mais c’est clairement la meilleure application de prise de notes gratuite disponible sous Linux et Android et la seule que je connaisse capable de dialoguer directement avec git.

Mise en place Ă©tapes par Ă©tapes

Initialisation du dépôt

Vous allez avoir besoin de :

Tout d’abord, j’ai crĂ©Ă© un dĂ©pĂ´t privĂ© vide sur Gitlab. Vous pouvez Ă©galement utiliser Github, les instructions devraient ĂŞtre similaires.

Clonez le dĂ©pĂ´t sur votre ordinateur avec git clone. Rendez-vous Ă  l’intĂ©rieur du dĂ©pĂ´t nouvellement crĂ©e et exĂ©cutez la commande hugo new site . --force. L’argument --force est nĂ©cessaire car git a crĂ©e des fichiers cachĂ©s et Hugo n’aime pas ĂŞtre initialisĂ© dans un dossier qui n’est pas vide.

Depuis Obsidian, vous allez pouvoir créer un coffre (vault) dans le dépôt que vous avez créé, au même endroit où Hugo a généré pleins de dossiers.

Une fois que c’est fait, rendez-vous dans les options d’Obsidian et plus prĂ©cisĂ©ment les plugins/greffons de la communautĂ©. Cherchez, installez et activez obsidian-git.

Vous pouvez paramétrer obsidian-git comme vous le désirez. Sachez que vous pouvez exécuter la plupart des commandes manuellement(pull pour récupérer les dernières modifications, commit pour enregistrer des modifications et push pour envoyer vos modifications enregistrées vers le serveur) depuis la palette de commandes de Obsidian Ctrl+P

Nous allons connecter le dossier contenant vos notes au reste du système plus tard, mais si vous voulez, vous pouvez déjà commencer à écrire des trucs.

Sur chacun des terminaux sur lesquels vous comptez prendre des notes, répétez la procédure à partir du clonage du dépôt.

Clônage du dépot sur mobile (facultatif)

Le cas du mobile est un peu particulier. L’extension obsidian-git n’est pas tout Ă  fait la mĂŞme sur portable et vient avec d’autres limitations. La plus reloue d’entre elle, c’est qu’elle n’est pas compatible avec l’utilisation de SSH. Si vous ne voyez pas oĂą est le problème, c’est que tout est bon pour vous.

Lancez Obsidian depuis votre portable et crĂ©ez un nouveau coffre (vault). Installez obsidian-git comme Ă  l’habitude. Depuis la palette de commande, lancez Obsidian Git: Clone an existing remote repo. Suivez les instructions et si tout se passe bien, l’application va vous demander de la redĂ©marrer.

Au moment de relancer l’application, vous allez remarquer que vous ĂŞtes actuellement Ă  la racine du dĂ©pĂ´t et non pas dans votre vĂ©ritable coffre, celui qui contient uniquement vos notes. C’est tout Ă  fait normal et il va falloir faire un petit peu de gymnastique.

Quittez ce coffre. Depuis Obsidian, faites Open folder as vault. Naviguez jusqu’Ă  votre dĂ©pĂ´t, sauf que cette fois-ci, vous allez bien sĂ©lectionner le dossier qui contient vos notes.

Allez dans les options de obsidian-git. Rentrez bien vos identifiants, vos informations d’auteurs. Mais surtout, dans “Custom base path”, mettez simplement .. Cela sert Ă  signifier au logiciel que le vĂ©ritable dĂ©pĂ´t git est le parent du dossier actuel.

Si vous ne voulez pas être un petit cochon qui laisse des traces de pneus, vous allez vouloir supprimer le dossier .obsidian qui a été créé à la racine du dépôt.

Ă€ ce stade, normalement, tout devrait fonctionner et vous devriez ĂŞtre en mesure de pull et push sans problème. En cas de soucis, voici quelques pistes que j’ai explorĂ©es en faisant mon propre dĂ©bogage.

N’hĂ©sitez pas Ă  me contacter en cas de problème.

Paramétrage de Hugo

Hugo est un gĂ©nĂ©rateur de site statique raisonnablement simple et puissant, mais il a plusieurs limitations. Il n’est notamment pas capable de lire les liens relatifs que nous allons lui demander d’interprĂ©ter. Pour cela, il faut installer 2 petits bouts de codes.

Dans le dossier layout, créez des répertoires de manière à avoir quelque chose qui ressemble à layout/_default/_markup. Dans ce dossier, on va créer deux fichiers :

Un fichier render-link.html avec le contenu suivant :

{{- $url := urls.Parse .Destination -}}
{{- $scheme := $url.Scheme -}}

<a href="
  {{- if eq $scheme "" -}}
    {{- if strings.HasSuffix $url.Path ".md" -}}
      {{- relref .Page .Destination | safeURL -}}
    {{- else -}}
      {{- .Destination | safeURL -}}
    {{- end -}}
  {{- else -}}
    {{- .Destination | safeURL -}}
  {{- end -}}"
  {{- with .Title }} title="{{ . | safeHTML }}"{{- end -}}>
  {{- .Text | safeHTML -}}
</a>

{{- /* whitespace stripped here to avoid trailing newline in rendered result caused by file EOL */ -}}

Un autre fichier render-image.html avec le contenu suivant :

{{- $url := urls.Parse .Destination -}}
{{- $scheme := $url.Scheme -}}

<img src="
  {{- if eq $scheme "" -}}
    {{- if strings.HasSuffix $url.Path ".md" -}}
      {{- relref .Page .Destination | safeURL -}}
    {{- else -}}
      {{- printf "/%s%s" .Page.File.Dir .Destination | safeURL -}}
    {{- end -}}
  {{- else -}}
    {{- .Destination | safeURL -}}
  {{- end -}}"
  {{- with .Title }} title="{{ . | safeHTML }}"{{- end -}}
  {{- with .Text }} alt="{{ . | safeHTML }}"
  {{- end -}}
/>

{{- /* whitespace stripped here to avoid trailing newline in rendered result caused by file EOL */ -}}

En ce qui concerne le reste de la configuration de Hugo pour construire le site et personnaliser son apparence, c’est un petit peu en dehors du champ de ce petit guide.

Je vous invite Ă  consulter la documentation de Hugo et si vous ĂŞtes dĂ©butant et complĂ©tement perdu, n’hĂ©sitez pas Ă  me contacter pour que je vous file un coup de main.

Pendant la conception de votre site, faites bien attention à systématiquement supprimer les dossiers /public et /content. Ils ne doivent pas atterrir dans le dépôt.

Publication automatique

Vous avez votre dépôt et vous pouvez désormais push/pull à loisir (ou automatiquement) pour synchroniser vos appareils entre eux. Si vous avez pris le temps de configurer Hugo, vous avez également un petit site mignon, mais sans contenu.

Ici, nous allons brancher vos notes Ă  Hugo et publier le rĂ©sultat automatiquement sur internet. Tout d’abord, il faut initialiser Gitlab Pages. Il s’agit du service d’hĂ©bergement web gratuit que propose Gitlab.

Rendez-vous dans la section “Pages” de votre dĂ©pĂ´t et suivez les instructions. Ne vous emmerdez pas trop avec ce que Gitlab vous demande, parce qu’on va rĂ©Ă©crire par-dessus un peu plus tard de toute façon.

Une fois Pages initialisĂ©e, rendez-vous dans la section Pipelines > Editor. Ici, insĂ©rez les instructions suivantes (n’oubliez pas de les relire et de modifier de ce qui doit l’ĂŞtre) :

build:
  image: rust:latest
  stage: build
  script:
    - cargo install obsidian-export
    - mkdir content
    - obsidian-export [dossier de vos notes]/ content/
  artifacts:
    paths:
    - content
  only:
  - main

pages:
  image: klakegg/hugo:alpine-ci
  stage: deploy
  script:
  - hugo
  artifacts:
    paths:
    - public
  only:
  - main

En principe, cela devrait dĂ©jĂ  fonctionner et vous pouvez vous arrĂŞter lĂ  pour cette section. Mais comme j’ai passĂ© beaucoup de temps Ă  comprendre comment Ă©crire cette merde, je vais expliquer un peu comment ça marche.

Dans le cadre de son système d’intĂ©gration continue (en gros, du code qui est exĂ©cutĂ© quand certaines conditions sont remplies sur le dĂ©pĂ´t), Gitlab crĂ©e automatiquement 3 Ă©tapes (stages), build, test et deploy

On vient s’incruster dans ces Ă©tapes pour mettre en place notre propre pipeline. La section build, qui intervient pendant la phase build - ça va jusqu’ici ? - est exĂ©cutĂ© en premier. Un conteneur qui contient pleins d’outils pour compiler en Rust est initialisĂ© par Gitlab et ça tombe bien puisque obsidian-export, un outil essentiel pour “purifier” vos notes, est codĂ© en Rust et a besoin d’ĂŞtre compilĂ©.

cargo install obsidian-export sert à télécharger et compiler obsidian-export, mkdir content créer le répertoire qui va contenir les fichiers de contenu que Hugo peut lire et la dernière commande sert simplement à laisser obsidian-export faire son travail.

L’instruction artifacts permet de signaler Ă  Gitlab qu’on veut garder le dossier “content” et son contenu crĂ©e pendant cette Ă©tape pour plus tard.

La section pages qui intervient pendant la phase deploy, la dernière sert uniquement à lancer Hugo pour traduire le contenu en site internet.

Si ça vous intĂ©resse, l’instruction only: - main signifie que tout ce pipeline ne sera lancĂ© que si on est dans la branche principale. Au besoin, remplacez par master si votre hĂ©bergeur de dĂ©pĂ´ts git cautionne l’esclavagisme.

Conclusion

Normalement, si vous êtes un peu débrouillard, vous devriez avoir un site internet qui se déploie automatiquement (bon, ça prend quand même quelques minutes) chaque fois que vous modifiez vos notes.

Je viens de mettre ce système en place pour moi-mĂŞme. Je ne sais pas encore quels genres de problèmes chiants je vais rencontrer. Je ferai un petit retour d’expĂ©rience après quelques mois d’usages et peut-ĂŞtre complĂ©ter le petit tutoriel.