📖 Documentation du site « Aux frontières du réel »

Version 1.0 — Guide d'utilisation

Ce document explique, pas à pas, comment gérer votre site Internet : ajouter une page, la modifier, la supprimer, changer le menu, etc.

Aucune connaissance en informatique n'est nécessaire. Il suffit de suivre les étapes dans l'ordre.

📑 Table des matières

1. À quoi sert ce site ?
2. Les trois dossiers importants
3. Le cycle de travail en 3 étapes
4. Comprendre la structure d'une page
5. Ajouter une nouvelle page
6. Modifier une page existante
7. Supprimer une page
8. Renommer une page
9. Créer un sous-dossier (une rubrique)
10. Les métadonnées en détail
11. Le menu : ordre et visibilité
12. Changer la page d'accueil
13. Lancer le programme de construction
14. Que faire en cas de problème ?
15. Lexique des mots utilisés

1. À quoi sert ce site ?

Le site est composé de pages écrites en Markdown (un format de texte très simple) et converties automatiquement en pages HTML (le format que les navigateurs savent afficher).

Vous écrivez vos pages en Markdown, vous lancez une commande, et le site se met à jour tout seul.

Vous n'avez jamais besoin de toucher au HTML.

2. Les trois dossiers importants

Voici les trois dossiers que vous devez connaître :

Règle d'or : vous écrivez toujours dans pages/. Le dossier html/ est généré automatiquement, vous ne le modifiez jamais.

3. Le cycle de travail en 3 étapes

À chaque fois que vous voulez modifier le site, vous suivez toujours ces trois étapes :

Étape 1 — Écrire ou modifier une page

Dans le dossier pages/, vous éditez un fichier .md avec votre éditeur de texte habituel (par exemple QuickEdit+ sur Android).

Étape 2 — Lancer le programme de construction

Vous ouvrez une console (Terminal, Termux, SSH…) et vous tapez :

php build.php

Ce programme va :

• Détecter uniquement les pages qui ont changé
• Les reconvertir en HTML
• Mettre à jour le menu si nécessaire
• Supprimer les pages qui n'existent plus

Le programme ne touche pas aux pages inchangées. Il est donc très rapide.

Étape 3 — Vérifier le résultat

Vous ouvrez votre site dans un navigateur (https://votredomaine.fr) et vous vérifiez que tout s'affiche correctement.

C'est tout. Ces trois étapes sont les seules dont vous avez besoin pour gérer votre site au quotidien.

4. Comprendre la structure d'une page

Chaque fichier .md dans pages/ ressemble à ceci :

<!--
title: "Accueil"
homepage: true
order: 1
description: "Présentation du site"
keywords: "accueil, présentation"
authors: "Michel Garnier"
background: "#ffffff"
-->

# Mon titre

Voici le contenu de ma page.

## Un sous-titre

Un peu de texte, une image, une liste...

- Premier point
- Deuxième point

Une page comporte deux parties :

1. Le bloc de métadonnées (tout en haut, entre <!-- et -->)
2. Le contenu (titre, texte, images…)

5. Ajouter une nouvelle page

Étape 1 — Créer le fichier

Dans le dossier pages/, créez un nouveau fichier .md.

Le nom du fichier détermine l'adresse de la page.

Exemples :

⚠️ Règles pour le nom du fichier :

• Utilisez des minuscules
• Utilisez des tirets - à la place des espaces
• Pas d'accents, pas de caractères spéciaux
• Terminez toujours par .md

Bons noms : contact.md, nos-services.md, a-propos-de-nous.md

Mauvais noms : Contact.md, nos services.md, à-propos.md

Étape 2 — Écrire le contenu

Ouvrez le fichier et écrivez :

<!--
title: "Contact"
menu: true
order: 0
description: "Nous contacter"
keywords: "contact, téléphone, email"
authors: "Michel Garnier"
background: "#ffffff"
-->

# Contact

Vous pouvez nous joindre au 04 00 00 00 00.

Notre adresse : 1 rue de la Mairie, 66310 Estagel.

Étape 3 — Construire le site

Dans la console :

php build.php

Le programme génère la nouvelle page et met à jour le menu.

Étape 4 — Vérifier

Ouvrez votre site et vérifiez que la nouvelle page apparaît dans le menu.

6. Modifier une page existante

1. Ouvrez le fichier .md dans le dossier pages/
2. Modifiez ce que vous voulez (texte, image, titre…)
3. Enregistrez
4. Lancez php build.php
5. Rechargez la page dans votre navigateur

C'est tout. Une seule page sera régénérée, pas les autres.

7. Supprimer une page

1. Supprimez le fichier .md dans le dossier pages/
2. Lancez php build.php

Le programme :

• Détecte que la page n'existe plus
• Supprime automatiquement le fichier .html correspondant
• Retire l'entrée du menu

Vous n'avez rien d'autre à faire.

8. Renommer une page

Pour renommer une page, procédez en deux temps pour que le programme nettoie correctement :

1. Supprimez l'ancien fichier .md
2. Lancez php build.php (l'ancien .html est supprimé)
3. Créez le nouveau fichier .md avec le nouveau nom
4. Lancez php build.php (le nouveau .html est créé)

Exemple : vous voulez renommer service.md en nos-services.md.

• Étape 1 : supprimez service.md
• Étape 2 : php build.php → service.html est supprimé
• Étape 3 : créez nos-services.md avec les mêmes métadonnées et contenu
• Étape 4 : php build.php → nos-services.html est créé

9. Créer un sous-dossier (une rubrique)

Pour regrouper plusieurs pages dans une rubrique (par exemple « Climat »), créez un sous-dossier dans pages/.

Exemple : vous voulez une rubrique « Climat » avec 3 pages.

Créez cette structure :

pages/
  climat/
    canicule.md
    secheresse.md
    ombrage.md

Important : le nom du dossier devient le titre de la rubrique dans le menu.

Puis lancez php build.php. Le menu affichera :

▸ climat
    Canicule
    Sécheresse
    Ombrage

Astuce : pour que le titre du dossier soit plus joli que son nom de fichier (par exemple « Climat » au lieu de « climat »), renommez le dossier directement : Climat/.

10. Les métadonnées en détail

Le bloc en haut de chaque fichier .md sert à décrire la page. Il doit toujours être placé en tout premier, avant tout autre contenu.

Exemple complet

<!--
title: "Titre de la page"
menu: true
order: 0
homepage: false
description: "Courte description pour Google (150 caractères max)"
keywords: "mot1, mot2, mot3"
authors: "Michel Garnier"
background: "#ffffff"
-->

Détail de chaque champ

Règles à respecter

• Chaque champ est sur une seule ligne
• Le nom du champ, puis :, puis un espace, puis la valeur
• La valeur est entre guillemets pour les textes
• Le bloc commence par <!-- et se termine par -->
• Aucun champ n'est obligatoire : si vous en oubliez un, la valeur par défaut s'applique

Valeurs par défaut si vous oubliez

11. Le menu : ordre et visibilité

Comment le menu est trié

Le menu fonctionne ainsi :

1. Les dossiers apparaissent en premier, triés alphabétiquement
2. Les pages sont triées par order croissant
3. Les pages avec order: 0 (valeur par défaut) sont triées alphabétiquement
4. Les pages avec order supérieur à 0 apparaissent avant celles avec order: 0

Résumé simple :

• order: 0 → tri alphabétique normal
• order: 1, order: 2, order: 3… → ordre imposé, prioritaire

Exemple concret

Vous avez 5 pages :

• Accueil avec order: 1
• Actualités avec order: 2
• Contact avec order: 3
• Galerie sans order (donc 0)
• Mentions légales sans order (donc 0)

Le menu affichera dans cet ordre :

Accueil
Actualités
Contact
Galerie
Mentions légales

Masquer une page du menu

Pour qu'une page existe (accessible par son adresse) mais n'apparaisse pas dans le menu, mettez :

menu: false

C'est utile pour les pages comme « Mentions légales » ou « Plan du site ».

12. Changer la page d'accueil

La page d'accueil est celle qui s'affiche quand on tape simplement https://votredomaine.fr sans rien d'autre.

Comment faire

Dans le fichier .md de la page que vous voulez comme accueil, ajoutez :

homepage: true

Puis retirez cette ligne de l'ancienne page d'accueil.

Important : il ne doit y avoir qu'une seule page avec homepage: true dans tout le site.

Ensuite

Lancez php build.php. Le programme génère automatiquement un fichier index.html qui pointe vers la bonne page.

13. Lancer le programme de construction

La commande normale

php build.php

C'est celle que vous utiliserez 99 % du temps. Elle est très rapide (1 à 2 secondes) car le programme ne régénère que ce qui a changé.

Si vous voulez tout régénérer

En cas de doute, ou si quelque chose semble cassé :

php build.php --force

Cette commande régénère toutes les pages, quoi qu'il arrive. Elle prend quelques secondes de plus mais garantit un site propre.

Ce que le programme affiche

Après chaque lancement, vous verrez un résumé comme ceci :

BUILD TERMINÉ en 1.12s
Mode           : incrémental
Menu régénéré  : non
Pages générées : 1
Pages supprimées : 0
Total de .md   : 150

• Mode : incrémental (normal) ou FORCE (avec --force)
• Menu régénéré : oui si le menu a changé, non sinon
• Pages générées : combien de pages ont été reconverties
• Pages supprimées : combien de pages obsolètes ont été nettoyées
• Total de .md : combien de pages existent au total

Que faire si le programme affiche "ERREURS" ?

Lisez les messages. Ils indiquent le fichier et le type de problème. Les causes les plus fréquentes :

• Un fichier .md a été supprimé mais est encore listé → relancez
• Un fichier .md a des métadonnées mal formées → vérifiez le bloc <!-- ... -->
• Un fichier .md contient du Markdown invalide → ouvrez-le et corrigez

14. Que faire en cas de problème ?

Le site ne se met pas à jour

1. Vérifiez que vous avez bien lancé php build.php
2. Videz le cache de votre navigateur (Ctrl+F5 ou Cmd+Shift+R)
3. Si rien ne change, lancez php build.php --force

Une page n'apparaît pas dans le menu

1. Vérifiez que le champ menu n'est pas sur false
2. Vérifiez que le fichier .md a bien été enregistré
3. Relancez php build.php --force

L'ordre du menu n'est pas celui voulu

1. Ouvrez les fichiers .md concernés
2. Vérifiez les valeurs order
3. Rappel : order: 1 passe avant order: 2, et les order: 0 sont triés alphabétiquement après ceux qui ont un order positif
4. Relancez php build.php --force

Le titre affiché n'est pas le bon

1. Vérifiez le champ title dans les métadonnées
2. S'il est absent, le programme utilise la première ligne # ...
3. S'il est absent aussi, il utilise le nom du fichier

Une page affiche du texte bizarre

Vérifiez que le bloc <!-- ... --> est bien fermé par -->. S'il manque, tout ce qui suit est considéré comme métadonnées et disparaît.

Je veux repartir de zéro

1. Supprimez le fichier .cache.json à la racine
2. Lancez php build.php

Le programme va tout reconstruire comme au premier jour.

15. Lexique des mots utilisés

🎯 Résumé en une page

Pour ajouter une page :

1. Créez un fichier .md dans pages/
2. Écrivez le bloc de métadonnées en haut
3. Écrivez le contenu en dessous
4. Lancez php build.php

Pour modifier une page :

1. Éditez le .md
2. Lancez php build.php

Pour supprimer une page :

1. Supprimez le .md
2. Lancez php build.php

En cas de doute :

php build.php --force

Règles d'or :

• Écrivez toujours dans pages/
• Ne touchez jamais à html/
• Sauvegardez régulièrement votre dossier pages/
• En cas de problème, --force résout la majorité des cas

Documentation version 1.0 — pour le site « Aux frontières du réel »

Dernière mise à jour : à compléter