Objectif : aider les créateurs de sites Jekyll à choisir le thème le plus adapté à la découvrabilité : Just the Docs (JTD) ou Minimal Mistakes (MM).

1. Méthodologie

• Analyse des fonctionnalités natives : balises SEO, sitemap, Open Graph…
• Tests Lighthouse (performance, accessibilité, bonnes pratiques SEO).
• Facilité d’enrichissement pour un·e débutant·e.

2. Tableau comparatif

3. Analyse détaillée

3.1 Just the Docs

• Orientation documentation interne.
• Structure sidebar robuste, mais pas d’automation SEO.
• Nécessite d’ajouter : jekyll-seo-tag, jekyll-sitemap, fichier robots.txt.

3.2 Minimal Mistakes

• Pensé pour blogs et sites publics.
• Meta tags complètes, prise en charge des réseaux sociaux.
• Plugins SEO déjà whitelisted pour GitHub Pages.

4. Recommandations

5. Checklist SEO rapide pour chaque thème

Just the Docs

• Ajouter à _config.yml : jekyll-seo-tag, jekyll-sitemap
• Créer robots.txt, sitemap.xml
• Renseigner title & description dans chaque page

Minimal Mistakes

• Vérifier les balises OG (og_image)
• Compléter front‑matter : last_modified_at
• Soumettre sitemap.xml à Google Search Console

6. Conclusion

Pour un projet destiné au grand public (blogs, sites pédagogiques, documentation externe), Minimal Mistakes offre une longueur d’avance nette en SEO out‑of‑the‑box.
Si votre priorité est la légèreté et la navigation type wiki, Just the Docs reste une option viable à condition d’ajouter les briques SEO manquantes.

Article publié dans le cadre du site “Découvrabilité & Citoyenneté”.

But : transformer vos analyses citoyennes en fiches structurées, faciles à parcourir, exporter et réutiliser.

1. Pourquoi une collection ?

• Organisation claire : séparer les « dossiers » des articles de blog.
• Front‑matter adapté : champs spécifiques (theme, source_data, license) sans polluer les posts.
• Endpoints JSON : chaque dossier devient un nœud réutilisable (API légère).

2. Déclarer la collection dans _config.yml

collections:
  dossiers:
    output: true          # génère des pages HTML
    permalink: /dossiers/:path/

✔️ output: true crée la page, permalink définit une URL stable /dossiers/slug/.

3. Créer le dossier physique

|_ dossiers/
   |_ _posts/      # (optionnel) si vous voulez la date
   |_ infrastructure-eau.md
   |_ open-data-stib.md

Minimal Mistakes détecte automatiquement dossiers/.

4. Modèle de front‑matter pour un dossier

---
layout: single
collection: dossiers      # obligatoire
title: "Open Data STIB : potentiel citoyen"
permalink: /dossiers/stib-open-data/
theme: "Mobilité & Open Data"
source_data: "API STIB v1"
license: "CC BY 4.0"
toc: true
---

Nouveaux champs (theme, source_data, license) : libres ou imposés par ton besoin.

5. Navigation automatique

Ajoute un lien dans _data/navigation.yml :

- title: "Dossiers"
  url: /dossiers/

La page index de la collection se crée toute seule si tu places un fichier dossiers/index.md minimal :

---
layout: collection
title: "Dossiers citoyens"
permalink: /dossiers/
---

Le layout collection intégré à Minimal Mistakes liste les items.

6. Afficher des métadonnées supplémentaires

Crée un include Liquid _includes/dossier-meta.html :

<ul class="dossier-meta">
  <li><strong>Thème :</strong> </li>
  <li><strong>Donnée source :</strong> </li>
  <li><strong>Licence :</strong> </li>
</ul>

Puis, dans chaque dossier, insère où tu veux :

<ul class="dossier-meta">
  
  
  
</ul>

7. Générer un endpoint JSON (optionnel)

Dans dossiers/index.json :

---
layout: null
permalink: /dossiers.json
---
[

  {"path":"_dossiers/energie-communes.md","relative_path":"_dossiers/energie-communes.md","excerpt":"Analyse des coopératives énergétiques locales.","previous":null,"id":"/dossiers/energie-communes","collection":"dossiers","next":{"path":"_dossiers/test-projet.md","relative_path":"_dossiers/test-projet.md","excerpt":"Dossier de démonstration : état actuel du projet Jekyll Minimal Mistakes et fonctionnalités mises en place durant la session.","previous":{"path":"_dossiers/energie-communes.md","relative_path":"_dossiers/energie-communes.md","excerpt":"Analyse des coopératives énergétiques locales.","previous":null,"id":"/dossiers/energie-communes","collection":"dossiers","next":{"path":"_dossiers/test-projet.md","relative_path":"_dossiers/test-projet.md","id":"/dossiers/test-projet","collection":"dossiers","url":"/dossiers/test-projet/","draft":false,"categories":[],"layout":"single","classes":"wide","title":"Prototype du site Découvrabilité & Citoyenneté","theme":"Test","toc":true,"slug":"test-projet","ext":".md","tags":[],"date":"2025-07-16 09:52:16 +0000"},"output":null,"content":"Contenu du dossier…\n","url":"/dossiers/energie-communes/","draft":false,"categories":[],"layout":"single","title":"Énergie citoyenne : l'exemple des communes","themes":["Mobilité","Open Data"],"slug":"energie-communes","ext":".md","tags":[],"date":"2025-07-16 09:52:16 +0000"},"id":"/dossiers/test-projet","collection":"dossiers","next":null,"output":null,"content":"## Contexte\n\nCe dossier **test** résume les étapes franchies lors de la mise en place du site :\n\n1. Installation du thème **Minimal Mistakes** et déploiement GitHub Pages.  \n2. Ajout d’articles tutoriels et contenus citoyens.  \n3. Mise en place de la recherche Lunr.js.  \n4. Création de la collection `dossiers` avec filtrage dynamique par thème.  \n5. Personnalisation basique (palette vert–lilas, police *Inter*).\n\n## Objectifs court terme\n\n| Tâche | Statut |\n|-------|--------|\n| Valider le filtrage multi‑thème | ✅ |\n| Ajouter un dossier « Mobilité » complet | ⏳ |\n| Brancher statistiques Plausible | ⏳ |\n\n## À retenir\n\n- Ce fichier sert uniquement de **sandbox** pour vérifier que la collection et le JS fonctionnent.  \n- Le champ `theme: \"Test\"` déclenche son affichage dans le menu déroulant.\n\n_Fin du dossier test._\n","url":"/dossiers/test-projet/","draft":false,"categories":[],"layout":"single","classes":"wide","title":"Prototype du site Découvrabilité & Citoyenneté","theme":"Test","toc":true,"slug":"test-projet","ext":".md","tags":[],"date":"2025-07-16 09:52:16 +0000"},"output":null,"content":"Contenu du dossier…\n","url":"/dossiers/energie-communes/","draft":false,"categories":[],"layout":"single","title":"Énergie citoyenne : l'exemple des communes","themes":["Mobilité","Open Data"],"slug":"energie-communes","ext":".md","tags":[],"date":"2025-07-16 09:52:16 +0000"},

  {"path":"_dossiers/test-projet.md","relative_path":"_dossiers/test-projet.md","excerpt":"Dossier de démonstration : état actuel du projet Jekyll Minimal Mistakes et fonctionnalités mises en place durant la session.","previous":{"path":"_dossiers/energie-communes.md","relative_path":"_dossiers/energie-communes.md","excerpt":"Analyse des coopératives énergétiques locales.","previous":null,"id":"/dossiers/energie-communes","collection":"dossiers","next":{"path":"_dossiers/test-projet.md","relative_path":"_dossiers/test-projet.md","excerpt":"Dossier de démonstration : état actuel du projet Jekyll Minimal Mistakes et fonctionnalités mises en place durant la session.","previous":{"path":"_dossiers/energie-communes.md","relative_path":"_dossiers/energie-communes.md","id":"/dossiers/energie-communes","collection":"dossiers","url":"/dossiers/energie-communes/","draft":false,"categories":[],"layout":"single","title":"Énergie citoyenne : l'exemple des communes","themes":["Mobilité","Open Data"],"slug":"energie-communes","ext":".md","tags":[],"date":"2025-07-16 09:52:16 +0000"},"id":"/dossiers/test-projet","collection":"dossiers","next":null,"output":null,"content":"## Contexte\n\nCe dossier **test** résume les étapes franchies lors de la mise en place du site :\n\n1. Installation du thème **Minimal Mistakes** et déploiement GitHub Pages.  \n2. Ajout d’articles tutoriels et contenus citoyens.  \n3. Mise en place de la recherche Lunr.js.  \n4. Création de la collection `dossiers` avec filtrage dynamique par thème.  \n5. Personnalisation basique (palette vert–lilas, police *Inter*).\n\n## Objectifs court terme\n\n| Tâche | Statut |\n|-------|--------|\n| Valider le filtrage multi‑thème | ✅ |\n| Ajouter un dossier « Mobilité » complet | ⏳ |\n| Brancher statistiques Plausible | ⏳ |\n\n## À retenir\n\n- Ce fichier sert uniquement de **sandbox** pour vérifier que la collection et le JS fonctionnent.  \n- Le champ `theme: \"Test\"` déclenche son affichage dans le menu déroulant.\n\n_Fin du dossier test._\n","url":"/dossiers/test-projet/","draft":false,"categories":[],"layout":"single","classes":"wide","title":"Prototype du site Découvrabilité & Citoyenneté","theme":"Test","toc":true,"slug":"test-projet","ext":".md","tags":[],"date":"2025-07-16 09:52:16 +0000"},"output":null,"content":"Contenu du dossier…\n","url":"/dossiers/energie-communes/","draft":false,"categories":[],"layout":"single","title":"Énergie citoyenne : l'exemple des communes","themes":["Mobilité","Open Data"],"slug":"energie-communes","ext":".md","tags":[],"date":"2025-07-16 09:52:16 +0000"},"id":"/dossiers/test-projet","collection":"dossiers","next":null,"output":null,"content":"## Contexte\n\nCe dossier **test** résume les étapes franchies lors de la mise en place du site :\n\n1. Installation du thème **Minimal Mistakes** et déploiement GitHub Pages.  \n2. Ajout d’articles tutoriels et contenus citoyens.  \n3. Mise en place de la recherche Lunr.js.  \n4. Création de la collection `dossiers` avec filtrage dynamique par thème.  \n5. Personnalisation basique (palette vert–lilas, police *Inter*).\n\n## Objectifs court terme\n\n| Tâche | Statut |\n|-------|--------|\n| Valider le filtrage multi‑thème | ✅ |\n| Ajouter un dossier « Mobilité » complet | ⏳ |\n| Brancher statistiques Plausible | ⏳ |\n\n## À retenir\n\n- Ce fichier sert uniquement de **sandbox** pour vérifier que la collection et le JS fonctionnent.  \n- Le champ `theme: \"Test\"` déclenche son affichage dans le menu déroulant.\n\n_Fin du dossier test._\n","url":"/dossiers/test-projet/","draft":false,"categories":[],"layout":"single","classes":"wide","title":"Prototype du site Découvrabilité & Citoyenneté","theme":"Test","toc":true,"slug":"test-projet","ext":".md","tags":[],"date":"2025-07-16 09:52:16 +0000"}

]

🎯 Utilisable comme API simplifiée pour un widget externe (Appsmith, Dash, etc.).

8. Checklist avant de pousser

• collections: ajouté dans _config.yml
• Dossier dossiers/ créé et peuplé
• Fichier dossiers/index.md (layout collection)
• Liens navigation mis à jour
• Build local (bundle exec jekyll serve) OK

9. Et après ?

• Recherche dédiée : activer Lunr.js sur /dossiers/.
• Filtres par thème : paramètre URL ?theme=Mobilite.
• Export CSV : page Liquid qui parcourt site.dossiers et crache un fichier CSV.

Tu tiens désormais un mini‑réseau de connaissances prêt à l’open data !

Enjeu : dans un monde saturé d’informations, rendre les contenus trouvables et accessibles n’est pas un luxe technique ; c’est une condition de la citoyenneté active.

1. Qu’entend‑on par « découvrabilité » ?

La découvrabilité désigne l’ensemble des pratiques et technologies qui permettent à un contenu (article, vidéo, jeu de données…) d’être repéré, indexé et compris par :

1. Les moteurs de recherche
2. Les plateformes sociales
3. Les humains (navigation, accessibilité, langage clair)

On ne peut pas exercer ses droits si l’information reste enfouie dans un PDF perdu…

2. Pourquoi est‑ce crucial pour la citoyenneté ?

3. Les 5 piliers d’une découvrabilité citoyenne

1. Accessibilité universelle
   • HTML sémantique, contrastes, sous‑titres, texte alternatif
2. Métadonnées structurées
   • jekyll-seo-tag, Schema.org, Dublin Core
3. Ouverture & interopérabilité
   • Formats ouverts (CSV, JSON, Markdown)
   • Licences libres (CC BY, CC BY‑SA)
4. SEO éthique
   • Balises title/description honnêtes, sans clickbait
   • Performance (Lighthouse > 90)
5. Mobilisation sociale
   • Partage sur les réseaux, newsletters, communautés locales

4. Bonnes pratiques immédiates pour ton site

• Ajouter un og_image pertinent pour chaque page 👉 /assets/images/og.jpg
• Rédiger un excerpt clair (150 caractères max)
• Structurer la navigation via _data/navigation.yml
• Publier les sources en open data (CSV/JSON) dans /data/
• Utiliser des notes de bas de page ¹ pour citer les références

5. Exemples inspirants

6. Checklist « Citoyen‑SEO » avant publication

• Titre descriptif (≤ 60 caractères)
• Description concise (≤ 160 caractères)
• Image OG 1200 × 630 px compressée (< 500 Ko)
• Liens internes cohérents (maillage)
• Fichier sitemap.xml valide
• Licence & auteur clairement indiqués

7. Conclusion

Favoriser la découvrabilité, c’est abattre les barrières entre l’information et celles·ceux qui en ont besoin. Pour une démocratie vivante, chaque lien clair, chaque balise bien remplie, chaque format ouvert est un pas vers plus de participation et d’autonomie.

Un bon front‑matter, c’est l’ADN de ta page : moteurs de recherche, réseaux sociaux et lecteurs humains s’y retrouvent… ou pas.

1. Pourquoi s’en préoccuper ?

• SEO : Google lit d’abord tes balises title et description.
• Partage social : Open Graph/Twitter Cards utilisent image, excerpt.
• Ergonomie : Minimal Mistakes gère le temps de lecture (read_time), le héros (header:), la sidebar, etc.

Moralité : Pas de front‑matter → pas de stratégie de découvrabilité.

2. Clés obligatoires

title: "Carte blanche : la STIB en Open Data"
description: "Analyse des données temps réel STIB pour une mobilité citoyenne."
permalink: /stib-open-data/
date: 2025-08-01
last_modified_at: 2025-08-03

3. Métadonnées sociales

image: /assets/images/stib-dashboard.jpg   # miniature OG
excerpt: "Une plongée dans les API STIB pour démocratiser l'info transport."
share: true       # Active les icônes de partage MM

4. Options Minimal Mistakes utiles

header:
  overlay_image: /assets/images/hero-stib.jpg
  overlay_filter: 0.3
classes: wide
read_time: false

5. Modèles prêts à copier

5.1 Article d’analyse longue

layout: single
title: "Analyse longue"
permalink: /analyse-longue/
categories: ["Analyse"]
tags: ["longread", "belgique"]
toc: true
related: true

5.2 Fiche outil

layout: single
title: "Outil — GeoJSONLint"
permalink: /outils/geojsonlint/
categories: ["Outils"]
tags: ["geojson", "validation"]
description: "Valide vos fichiers GeoJSON en un clic."
header:
  overlay_filter: 0.15

6. Tester son front‑matter

1. Local : bundle exec jekyll build → avertissements.
2. GitHub Actions : l’étape pages/build échoue si front‑matter mal formé.
3. Lighthouse SEO : vérifie balises manquantes.
4. jekyll doctor : repère dates invalides, titres vides.

7. Checklist rapide avant git push

• Titre & description uniques
• permalink sans majuscules ni espaces
• last_modified_at mis à jour
• Image OG compressée (< 500 Ko)
• Aucune balise YAML vide ou en double

8. Vers la suite

Prochain niveau : créer ta collection dossiers pour publier des cas d’étude citoyens structurés (YAML + Markdown). Reste branché !

Objectif : obtenir un site fonctionnel avec le thème Minimal Mistakes, hébergé gratuitement sur GitHub Pages – sans Ruby local, sans ligne de commande complexe. Comptez environ 10 minutes, café compris.

1. Prérequis ultra-light

2. Créer le dépôt en un clic

1. Ouvre le repo starter : https://github.com/mmistakes/mm-github-pages-starter
2. Clique sur Use this template → Create a new repository
3. Nomme ton dépôt (par exemple citoyennete-mm-site)
4. Choisis Public pour GitHub Pages gratuit
5. Clique Create repository

GitHub clone alors le thème avec la config et un contenu de démonstration.

3. Modifier _config.yml

url: "https://ton-pseudo.github.io"
baseurl: "/citoyennete-mm-site"  # mettre "" si le site est à la racine
title: "Découvrabilité & Citoyenneté"
description: "Tutoriel et articles pédagogiques construits avec Minimal Mistakes"
remote_theme: "mmistakes/minimal-mistakes@4.27.1"

4. Activer GitHub Pages

1. Va dans Settings → Pages de ton dépôt
2. Source : Deploy from a branch et sélectionne main
3. Patiente une minute : ton site apparaît à https://ton-pseudo.github.io/citoyennete-mm-site/

🎉 C’est en ligne !

5. Personnaliser la page d’accueil

• Édite index.md
• Mets le menu à jour dans _data/navigation.yml
• Ajoute ta bio dans _data/authors.yml

6. Bonnes pratiques SEO immédiates

1. Vérifie la présence de jekyll-seo-tag dans _config.yml
2. Ajoute title, description et last_modified_at dans chaque front‑matter
3. Laisse GitHub générer sitemap.xml et feed.xml
4. Place /assets/images/og.jpg (1200 × 630 px, ≤ 500 Ko) et référence‑le :

seo:
  og_image: /assets/images/og.jpg

7. (Facultatif) Développer localement

gem install bundler
git clone https://github.com/ton-pseudo/citoyennete-mm-site.git
cd citoyennete-mm-site
bundle install
bundle exec jekyll serve

Puis visite http://localhost:4000.

8. FAQ express

9. Aller plus loin

Passe au tutoriel suivant pour créer une collection dédiée, styliser ta palette, et activer la recherche interne.

Objectif : transformer l’apparence par défaut de Minimal Mistakes en une identité cohérente avec vos couleurs, votre typo et quelques touches CSS.

1. Principe général

1. Surcharger SCSS via assets/css/_custom.scss (ou custom.scss en racine assets/css/)
2. Ajouter, au besoin, un head/custom.html pour importer des polices externes
3. Ajuster le layout avec les classes utilitaires déjà fournies (classes: wide, image-feature)
4. Garder la compatibilité GitHub Pages (pas de plugins Ruby additionnels)

2. Créer ou activer le fichier SCSS

Dans assets/css/ ajoute :

/* _custom.scss */
// Palette vert & lilas
$body-link-color: #6b5b95;
$primary-color:    #88b04b;
$masthead-background: #ffffff;

// Titres en Police Google 'Inter'
$global-font-family: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI",
                     Roboto, "Helvetica Neue", Arial, sans-serif;

// Accent infos (ex. notice)
.notice--primary {
  background: mix($primary-color, #fff, 15%);
  border-left: 4px solid $primary-color;
}

Minimal Mistakes compile automatiquement ce fichier pendant le build GitHub Pages car il l’inclut dans main.scss.

3. Importer une police Google (optionnel)

1. Crée _includes/head/custom.html
2. Colle :

<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;600&display=swap" rel="stylesheet">

1. git add _includes/head/custom.html

Votre $global-font-family pointera vers Inter (déjà défini dans SCSS).

4. Étendre la largeur de certaines pages

Dans un front‑matter :

classes: wide

ou full‑width (aucune marge) :

classes: full

Idéal pour des dashboards ou images larges.

5. Boutons personnalisés

.btn--citoyen {
  @extend .btn;
  background: $primary-color;
  &:hover { background: darken($primary-color, 7%); }
}

Puis dans un article :

<a href="/dossiers/" class="btn btn--citoyen">Voir les dossiers</a>

6. Exemple complet

Demo : /assets/images/og.jpg comme hero verdâtre + classes wide.
Essayez sur la page “Découvrabilité & Citoyenneté”.

header:
  overlay_image: /assets/images/hero-demo.jpg
  overlay_filter: 0.2
classes: wide

7. Checklist avant push

• assets/css/_custom.scss présent
• Pas d’erreur de compil Sass (bundle exec jekyll build local)
• _includes/head/custom.html si police externe
• og_image rafraîchi pour vos réseaux

Tout prêt ? Commit + push puis admirez votre nouveau style !

8. Aller plus loin

• Icônes : @lucide-icons en SVG inline
• Mode sombre : surcharge $body-background-color--dark
• Micro‑animations : ajouter @keyframes dans _custom.scss.

Faites‑vous plaisir, l’esthétique aussi est un acte citoyen.