Les trois gestes
1. Poser le fichier
Une page est un .html déposé dans public/pages/. Si elle a des
ressources à elle (données, images, scripts), lui donner un dossier et y mettre un
index.html :
public/pages/ma-page.html → /pages/ma-page.html
public/pages/mon-outil/index.html → /pages/mon-outil/
public/pages/mon-outil/donnees.json (ressource de l'outil)
Le dossier public/ est le dépôt publié, et rien d'autre ne l'est.
Ce qui est versionné est exactement ce qui part en ligne : les notes de travail et
l'outillage vivent au-dessus, hors du dépôt, et ne peuvent donc pas être publiés par
inadvertance.
Nom de fichier en minuscules, tirets, sans accent ni espace — il devient l'adresse publique de la page.
2. Renseigner les deux champs
L'index se construit en lisant les pages elles-mêmes. Deux balises du <head>
sont obligatoires, sans quoi la page apparaîtra sans titre lisible :
<title>Le titre affiché dans l'index</title>
<meta name="description" content="La ligne qui apparaît sous le titre.">Il n'y a aucune liste de pages à tenir à jour ailleurs. L'information vit dans le fichier, à un seul endroit.
Facultatif : déclarer d'autres métadonnées
Une page peut porter un bloc de métadonnées libre, valide en HTML et ignoré à l'affichage. Tout ce qu'il contient est repris tel quel dans index.json :
<script type="application/json" id="meta">
{"date": "2026-08-10", "type": "mode-emploi", "statut": "stable"}
</script>
Les champs sont libres — aucun vocabulaire imposé. Ils ne peuvent pas écraser
titre, description ni lien, qui restent la
source de l'index. Un JSON invalide est signalé et ignoré, jamais deviné.
Déclarer plutôt que déduire. Une date de modification prise sur le fichier n'est pas fiable : cloner le dépôt remet tous les horodatages à la date du clone. Ce qui est déclaré dans la page voyage avec elle et ne change que si quelqu'un le change.
Le site se lit aussi à la machine
index.json est le même index que la page d'accueil, sous forme exploitable : un outil le lit une fois et connaît toutes les pages, sans avoir à parser du HTML ni à lister un dossier.
Il ne contient aucune URL absolue — les chemins y sont relatifs au fichier lui-même. Il reste donc juste si le site change d'hébergeur, de domaine, ou descend dans un sous-dossier. Le générateur le réécrit en même temps que l'index visible : les deux ne peuvent pas diverger.
3. Régénérer l'index
python outils/generer_index.py
Le script relit tout public/pages/ et réécrit la zone des pages dans
public/index.html. Il n'écrit nulle part ailleurs.
Ce qu'une session ne touche pas
| Élément | Règle |
|---|---|
index.html, entre PAGES:DEBUT et PAGES:FIN |
Zone régénérée. Toute édition à la main y sera écrasée au prochain passage du script. L'en-tête et le pied de page, eux, s'éditent normalement. |
| Les pages des autres sessions | On ajoute la sienne. On ne réécrit pas celle d'une autre sans demande explicite. |
style.css |
Feuille commune. On peut y ajouter, pas y retirer : une classe supprimée casse les pages déjà en ligne qui s'en servent. |
.nojekyll |
Fichier vide indispensable, à la racine du dépôt. Sans lui, l'hébergeur ignore tout fichier ou dossier commençant par un tiret bas. |
Deux pièges qui ne se voient qu'en ligne
Les chemins absolus
Une page qui charge une ressource par un chemin absolu du disque, ou par
file:///…, fonctionne en local et s'affiche vide une fois publiée.
Uniquement des chemins relatifs, et les ressources à côté de la page qui les utilise.
La casse des noms
Windows ne distingue pas Donnees.json de donnees.json ;
le serveur, si. Une page peut donc marcher en local et renvoyer une erreur en ligne.
Écrire les noms en minuscules et les appeler exactement tels quels.
Le site est public
Tout ce qui est déposé ici est lisible par n'importe qui et indexable par les moteurs de recherche. Rien d'autre ne doit y entrer.