blog/2025

Files

Richard Dern cfeb699e8b Directive sur les apostrophes et guillemets

2025-12-13 17:52:00 +01:00

15 KiB

Raw Blame History

AGENTS.md

Présentation du projet

Ce projet contient les sources de mon blog. Il s'agit d'un site statique généré avec Hugo, dont la version peut être vérifiée avec la commande hugo version.

Instructions générales

Interactions avec l'utilisateur

L'utilisateur préfère être vouvoyé
Répondre à l'utilisateur en français, quelle que soit la langue utilisée ailleurs
Si une demande prête à confusion, demander une clarification à l'utilisateur plutôt que d'essayer de deviner
L'utilisateur préfère considérer l'agent comme une entité féminine
L'agent est un expert du développement web et maitrise toute technologie afférente
L'utilisateur préfère qu'on s'adresse à lui avec un ton bienveillant, en utilisant un vocabulaire soutenu, approprié au contexte
L'autisme de l'utilisateur doit être pris en compte au cours des échanges
L'utilisateur peut parfois perdre patience : la discussion doit être désamorcée rapidement par une solution que l'agent mettra en place, testera et modifiera jusqu'à ce qu'elle produise le résultat escompté

Git

Ne jamais faire de git push automatiquement, sauf si demandé explicitement
Les commits doivent être atomiques
Les commits sont écrits en français
Aucun commit ne doit être effectué sans demande explicite de l'utilisateur

Code

Le code doit être architecturé, propre, clair, concis, minimaliste
- Préférer la création de plusieurs petits fichiers pour éviter le code monolithique
- Ne pas implémenter de fonctionnalités non demandées
- Respecter les principes DRY, KISS et SOLID
- Si une librairie existe pour accomplir une tâche donnée, exploiter cette librairie
  - S'assurer de sa popularité et de son activité récente
Le code doit être écrit en anglais mais documenté en français, lisible par un humain
- Documenter clairement toutes les fonctions et méthodes
- Choisir des noms de variables appropriées et compréhensibles, tout en restant courts
La gestion des erreurs est considérée comme dangereuse
- On ne doit jamais utiliser de fallbacks
- On ne doit jamais utiliser de structures de type try/catch
Le code est écrit pour être spécifique à mon site
- Je suis l'unique utilisateur des outils créés
- Le code doit être compris de tous, mais pas adaptable à tous

Outils en console

S'assurer de l'harmonisation des entrées/sorties
- Toujours utiliser le français dans les interactions avec l'utilisateur

Python

Accéder à l'environnement virtuel via la commande source .venv/bin/activate
Renseigner les dépendances dans le fichier requirements.txt

Javascript

Mettre à jour régulièrement les dépendances
Auditer régulièrement les dépendances avec npm audit

CSS

Le thème de base est nommé 42 (themes/42) (référence à H2G2, mais aussi parce que je l'ai créé à l'occasion de mon anniversaire)
Je n'utilise aucun framework connu ; je fais du CSS "vanilla"
Nous ne supporterons jamais de thème clair
Il fait usage de variables CSS définies dans themes/42/assets/css/variables
L'agent peut créer de nouvelles variables, à condition de respecter les conventions de nommage des autres variables
Ce thème de base peut être hérité par d'autres thèmes
- Le thème par défaut est actuellement themes/default
- Un thème hérité n'est censé devoir surcharger que les variables qualifiées "d'esthétique" (telles que les couleurs ou les effets visuels), par opposition aux variables qualifiées de "structurelles" (telles que les marges ou le positionnement)
Le CSS doit rester le plus simple possible
- On ne doit pas exploiter d'effets visuels complexes tels que les agrandissements, les shifts, les apparitions ou disparitions progressives, etc.
Le code CSS doit respecter les règles d'accessibilité pour le contenu, notamment :
- Taille des polices
- Contrastes entre le texte et le fond de son container
On doit créer le moins de classes possibles, et préférer styliser les balises HTML directement
On peut utiliser la notation imbriquée (nested) par mesure de lisibilité

Instructions relatives aux articles

Ne pas utiliser les apostrophes et les guillemets typographique dans le markdown

Structure du contenu

Tout le contenu publié réside dans le dossier content/
Un dossier contenant un fichier index.md est un bundle
Tous les articles sont des bundles
Si un dossier ne contient pas de fichier index.md, c'est une section
Une section ne contenant que des bundles est une section-feuille, autrement appelée thématique
Un bundle peut contenir :
- Un ou plusieurs dossiers images, diagrams, sounds, videos, contenant les pièces jointes du bundle
- Un dossier data, pouvant notamment contenir des métadonnées associées aux pièces jointes

Sections de premier niveau

Collections (`content/collections/`)

Les premiers dossiers, enfants directs de content/collections/, désigne une marque proposant des objets que je collecte ; ce sont les dossiers de marque
- content/collections/lego contient ma collection d'objets LEGO.
Chaque dossier de marque peut contenir un ou plusieurs dossiers de thèmes
- content/collections/lego/jurassic-world contient ma collection d'objets LEGO sur le thème de Jurassic World
Chaque dossier de thème contient un ou plusieurs bundes d'objets de collection, chacun représentant un et un seul objet

Critiques (`content/critiques/`)

Contient mes critiques de médias (liste non exhaustive, pouvant évoluer avec le temps) :
- content/critiques/films pour mes critiques de films
- content/critiques/series pour mes critiques de séries TV
- content/critiques/jeux-video pour mes critiques de jeux-vidéo
- content/critiques/livres pour mes critiques de livres
Chaque média contient directement un ou plusieurs bundles représentant l'oeuvre critiquée
Le titre original est utilisé, pas le titre français

Intérêts (`content/interets/`)

Articles de fond sur des sujets qui m'intéressent
Ce dossier contient un sous-dossier par thématique principale
- astronomie
- microscopie
- informatique
- etc.
Chaque thématique contient une arborescence structurée en année, mois, jour et bundles
- Exemple : Si l'on découpe le chemin physique content/interets/electronique/2025/10/21/pilotage-d-un-switch-usb-par-le-wifi, on sait qu'on est dans le bundle pilotage-d-un-switch-usb-par-le-wifi, publié le 21/10/2025 dans la section électronique

Liens intéressants (`content/interets/liens-interessants`)

Cette section a le même usage que l'application Shaarli : je m'en sers pour partager avec mes lecteurs mes trouvailles sur Internet
J'ajoute un lien avec la commande node tools/add_link.js "<url>", qui produit le bundle correspondant, récupère le titre et la description du site distant, ainsi qu'une capture d'écran placée dans le dossier images/ du bundle créé
Si une description est trouvée, elle est ajoutée dans le corps du fichier index.md généré par le script
Je peux éventuellement ajouter un commentaire personnel dans le corps du fichier index.md, mais ce n'est pas systématique

Pièces jointes

Un bundle peut contenir une ou plusieurs pièces jointes, selon leur type parmi (liste non exhaustive et pouvant évoluer avec le temps) :
- images
- videos
- sounds
- diagrams
Chaque pièce jointe peut être accompagnée de métadonnées placées dans le dossier data du bundle
- Par exemple, l'image {chemin du bundle}/images/1.png peut avoir un fichier de métadonnées placé dans {chemin du bundle}/data/images/1.yaml

Métadonnées

Un fichier de métadonnées d'une pièce jointe à un bundle est nécessairement au format yaml, doté des attributs suivants :
- title : Titre du document (utilisé par l'attribut HTML title)
- description : Description libre ajoutée au document (affiché dans une balise figcaption par exemple)
- attribution : Si le fichier n'a pas été créé par l'utilisateur
- prompt : Si le fichier a été généré par l'Intelligence Artificielle, cet attribut doit contenir le prompt utilisé pour le générer
Aucun attribut de ce fichier n'est requis ; ils peuvent rester vides ou être précédés par le caractère #
Le fichier de métadonnées n'est pas requis ; s'il existe, il peut être vide

Frontmatter

Tout fichier index.md doit avoir un frontmatter contenant au moins les attributs suivants :
- title : Titre que je donne à mon article
- date : Si possible avec l'heure, mais la majorité de mes articles actuels ne contiennent que la date
Le frontmatter peut contenir d'autres attributs optionnels, autres que les taxonomies :
- cover : Chemin vers l'image illustrant l'article. Cette image doit être stockée dans le dossier {chemin du bundle}/images/. Elle sera utilisée pour générer la vignette de l'article, et affichée en en-tête de l'article. Je la désigne par cover, image de couverture, ou image d'en-tête
- dossier : Plusieurs bundles partageant une même valeur pour l'attribut dossier seront regroupés dans un dossier virtuel tout en résidant physiquement dans leurs dossiers physiques respectifs
  - Exemple : dossier: [ "Exploitation de mes données météo" ]
  - Cet attribut devrait être complété par un attribut weight
    - Par exemple :
```
dossier: [ "Exploitation de mes données météo" ]
weight: 10
```
  - links : Peut contenir un ou plusieurs objets indiquant des liens associés au bundle. Par exemple :
```
links:
- name: Page d'origine
  url: https://openbadgefactory.com/obv3/credentials/f421c3c8ae974fa2191b3482b05f37b4e1bc8c4b
  lang: fr
```
```
- Les attributs `name` (titre du document) et `url` sont requis
- L'attribut `lang` ne doit être renseigné **que** si l'on connait avec certitude la langue du document distant
```
Le frontmatter doit être séparé du corps de l'article par une ligne vide

Markdown

Lorsque l'utilisateur demande à être aidé pour la rédaction de ses articles, employer un ton neutre, utiliser un vocabulaire approprié au sujet traité
Rester neutre, objectif, factuel
Présenter des sources vérifiables lors de toute affirmation portant sur un concept-clé, sous la forme de liens markdown vers :
- la Wikipédia en français (ou à défaut, en anglais)
- une ou plusieurs études scientifiques, si approprié
Corriger l'attribut date du frontmatter lorsqu'il est renseigné mais incomplet, pour indiquer la date et l'heure courante, dans un format supporté par Hugo. Ne jamais ajouter l'attribut s'il n'existe pas déjà.
Les sections démarrent toujours au deuxième niveau dans le corps du markdown (##)
Ne jamais ajouter de numérotation aux sections
Ne jamais utiliser de caractères comme les emojis dans les sections
Ne jamais ajouter d'émojis dans le corps de l'article
Ne jamais supprimer les émojis existant

Outils

Les outils sont placés dans le dossier tools/
Les librairies créées sur mesure devront être placée dans tools/lib/, éventuellement dans un sous-dossier pour architecturer correctement le code

Ajout d'un LEGO à ma collection (`tools/add_lego.js`)

Ce script exploite l'API du site Rebrickable pour me permettre de récupérer des images et informations à propos d'un set LEGO donné et ajoute ou modifie le bundle correspondant

Ajout d'un lien intéressant (`tools/add_link.js`)

Prend en entrée un URL et crée un nouveau bundle en peuplant l'attribut links du frontmatter et en fournissant une image d'en-tête

Ajout de la météo (`tools/add_weather.js`)

Ajoute les informations sur la météo à un bundle (ou tous les bundles)
Ces informations sont tirées de mon serveur InfluxDB2, ou d'au moins une source externe si ces données ne sont pas disponibles

Vérification des liens

Externes (`tools/check_external_links.js`)

Vérifie la disponibilité des sites liés partout dans content/ (code HTTP 200 ou autre)
On cherche les liens dans les fichiers markdown (incluant le frontmatter) et les fichiers *.yaml
On ignore les URL placés dans des blocs de code mono ou multilignes
La vérification enrichie repose sur Playwright et le Chromium embarqué par la librairie playwright
- La variable externalLinks.usePlaywright de tools/config/config.json doit être positionnée à true pour activer cette vérification
- L'attribut externalLinks.playwrightExecutablePath doit rester vide ou à null afin de laisser Playwright utiliser son propre navigateur, compatible avec la configuration nix-ld déclarée dans /etc/nixos/nix-ld-libraries.nix
- Si externalLinks.playwrightExecutablePath est renseigné, il doit impérativement pointer vers un binaire existant : dans le cas contraire, le script se termine en erreur et interrompt le déploiement

Internes (`tools/check_internal_links.js`)

Vérifie les liens morts internes
Pas besoin de lancer Hugo : il suffit de chercher tous les liens sans :// dans content/
On cherche les liens dans les fichiers markdown (excluant le frontmatter) et les fichiers *.yaml
On ignore les URL placés dans des blocs de code mono ou multilignes
L'URL est de la forme /{section ou bundle} : on cherche l'existence du dossier content/{section ou bundle}, et la présence d'un fichier index.md ou _index.md dans ce dossier, s'il existe. Si un tel fichier existe : le lien est valide.

Diagrammes mermaid (`tools/generate_mermaid_diagrams.js`)

Cherche des fichiers *.mermaid dans un dossier diagrams des bundles
Pour chaque fichier *.mermaid trouvé, on lance l'exécutable de mermaid sur ce fichier pour produire l'image correspondante dans le dossier images/ du bundle
Les images produites doivent être au format .png ou .jpeg
Voir content/interets/electronique/2025/10/21/pilotage-d-un-switch-usb-par-le-wifi

Génération de métadonnées (`tools/generate_metadata_files.js`)

Génère automatiquement les fichiers de métadonnées pour toute pièce jointe du dernier bundle créé et les place dans le dossier data/ du bundle

Générateur de statistiques (`tools/generate_stats.js`)

Génère diverses statistiques intéressantes
Les statistiques sont présentées dans le bundle content/stats

Synchro Wikipédia (`tools/sync_wiki_metadata.js`)

Ce script est utile aux critiques de médias
Il cherche sur la Wikipédia/Wikidata des informations relatives aux oeuvres critiquées

Déploiement

Tout le déploiement du site est confié au script deploy.sh.
Certains scripts sont exécutés avant le déploiement. S'ils modifient des fichiers dans content/, leur exécution doit stopper le déploiement et informer l'utilisateur que des fichiers ont été modifiés
- Exploiter set -euo pipefail pour éviter les blocs if à chaque script

15 KiB Raw Blame History