feat: ajout de la documentation et des workflows pour la publication du site sur GitHub Pages

hrenaud · hrenaud · commit de4a0ae4b7e0 · 2025-10-09T13:39:41.000+02:00
diff --git a/.github/workflows/retype-action.yml b/.github/workflows/retype-action.yml
@@ -0,0 +1,30 @@
+name: Publish Retype powered website to GitHub Pages
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+
+jobs:
+  publish:
+    name: Publish to retype branch
+
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-dotnet@v1
+        with:
+          dotnet-version: 7.0.x
+
+      - uses: retypeapp/action-build@latest
+        with:
+          config_path: ./docs/retype.yml
+
+      - uses: retypeapp/action-github-pages@latest
+        with:
+          update-branch: true
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,34 @@
+---
+label: Home
+icon: home
+order: 100
+---
+
+# GenRefs, le générateur de site référentiels par Green IT.
+
+## Objectifs et contraintes
+
+Les référentiels Green IT sont hébergés depuis 2021 sur GitHub :icon-mark-github: pour laisser l'accès libre à nos travaux. GitHub, basé sur Git ajoute la possibilité de tracer les versions :icon-versions:, les contributeurs :icon-people:... et aussi de discuter :icon-comment-discussion: sur chaques bonnes pratiques, permettant le débat et ainsi avoir une trace des échanges qui ont aboutis à un concensus.
+
+Le format Markdown :icon-markdown:, simple, open-source et universel, est utilisé pour permettre d'avoir une bonne lisibilité des contenus structurés grâce à une mise en page, permise par le langage et bien rendu par GitHub. Mais cela reste un support de "nerds" :)
+
+Lors de la création du [Référentiel d'écoconception pour WordPress](https://rwp.greenit.fr), nous avons décider, pour faciliter l'accès à la connaissance sur l'écoconception, de faire, en plus de ces documents Markdown, un site web plus lisible encore, et surtout utilisable pour "Monsieur et Madame tout le monde", qui est une des cibles de ce référentiel.
+
+### En résumer
+
+- **Objectifs**
+  - Être sur GitHub :icon-mark-github: pour tracer les versions et profiter des facilités offertes ;
+  - Rendre accessible la connaissance au plus grand nombre => Pas que du Markdown :icon-markdown: et pas que dans un repo ;
+  - Rendre la contribution simple au moins technique => Avoir un CMS ;
+  - Pouvoir multiplier les sites de référentiels "simplement".
+- **Contraintes**
+  - Utiliser une base de fichier Markdown :icon-markdown: => Ne pas utiliser une base de données classique, donc pas un CMS classique, mais un `git-cms` ;
+  - Heberger les contenus sur GitHub :icon-mark-github: et qu'ils restent lisible.
+
+### Conclusion
+
+Après plusieurs évaluations de solutions, plusieurs versions nous avons abouti à une "stack" qui répond à nos besoins et contraintes :
+
+- [TinaCMS](https://tina.io/), pour sa simplicité utilisation lors de la contribution, qu'il soit un `git-cms`, qu'il soit open-source et auto-hébergeable, et surtout qu'il utilise le format Markdown pour gérénerer ses contenus
+- [NextJS](https://nextjs.org/), pour sa bonne intégration à TinaCM
+- [Vercel](https://vercel.œom) comme hébergeur. Ce n'est pas par choix, mais c'est le seul moyen pour hébergé le CMS.
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -0,0 +1,184 @@
+---
+label: Configuration
+icon: tools
+order: 10
+---
+
+# Configuration d'un Réferentiel
+
+## Introduction
+
+Tous les référentiels utilisent la même base technique pour simplifier et uniformiser la contribution/consultation/développement.
+
+!!!info Langue de l'interface et des contenus
+Tous les référentiels sont prêts à être multilingues `FR`, `EN` et `ES`.  
+Pour toute autre langue, il faudra traduire l'interface.
+!!!
+
+## Création d'un nouveau site
+
+!!!tip
+**Pour la création d'un nouveau site de référentiel, il faudra fournir toutes les informations détaillées ci-dessous au responsable.**
+!!!
+
+## Fonctionnalités proposées :
+
+!!!warning Point d'attention
+Il existe 2 bases de configuration, `RWEB` et `RWP` car ils n'ont pas la même façon de gérer les métadonnées (Cycle de vie, MOE, Impacts Environnementaux, etc.) et n'ont pas les mêmes fonctionnalités.
+!!!
+
+### Languages
+
+- `fr`: 🇫🇷 Français,
+- `en`: 🇬🇧 English,
+- `es`: 🇪🇸 Español,
+
+### Lexique
+
+Le lexique à pour but de partager une explication de certains mots clés. Ce sont des fiches Markdown, mais affichées uniquement dans une page de liste.
+
+**Si activés :**
+
+- Affichage dans la navigation de `Lexique` et un lien vers la page de liste ;
+- Possibilité de contribuer aux fiches dans le CMS.
+
+!!!tip
+Souhait d'évolution, que les fiches de bonnes pratiques permettent d'afficher au survol le contenu du lexique.
+!!!
+
+### Lien vers les Personas
+
+Par défaut, il faut assigner des personas aux fiches de bonnes pratiques, mais on peut activer l'affichage d'un lien vers la page décrivant le persona. Il faut donc créer autant de personas que de langues.
+
+**Si activés :**
+
+- Un lien est cliquable dans la barre des métadonées dans chaque fiche.
+
+### Priorité d'implémentation
+
+!!!success
+**Obligatoire**
+!!!
+
+Il y deux types d'affichages :
+
+- **RWEB** : Une note de 1 à 5
+- **RWP** : Une note de 1 à 3 avec des 👍
+
+### Impacts environnementaux
+
+!!!success
+**Obligatoire**
+!!!
+
+Il y deux types d'affichages :
+
+- **RWEB** : Une note de 1 à 5
+- **RWP** : Une note de 1 à 3 avec des 🌱
+
+### (Difficulté de) Mise en Œuvre
+
+Calcul automatisé utilisant la `Priorité d'implémentation` et les `Impacts environnementaux` si ils sont configurés pour utiliser la note de 1 à 5 (sans emoji).
+
+**Si activés :**
+
+- La note MOE s'affiche dans la barre des métadonnées des fiches.
+
+!!!info
+N'est pas utilisé dans `RWP`.
+!!!
+
+### Lifecycle (Cycle de vie)
+
+!!!success
+**Obligatoire**
+!!!
+
+Les étapes du cycle de vie.
+
+1. Specification
+2. Concept
+3. Development
+4. Production
+5. Utilization
+6. Support
+7. Retirement
+
+### Scope (Périmètre)
+
+Pour permètre de préciser quand réaliser la bonne pratique en plus du lifecycle.
+
+!!!info
+Comme les BP de `RWP` s'adressent à des publics différents, la mise en œuvre d'une bonne pratique peut se faire à des moments différents.
+
+**N'est pas utilisé dans `RWEB`.**
+!!!
+
+- Cache
+- Documents
+- Fonctionnalités
+- Images
+- Front-office
+- Hébergement
+- Performance
+- Sécurité
+- SEO
+- Stockage
+- Thèmes
+- Vidéos/Audios
+
+**Si activés :**
+
+- En contribution et en front, l'information est disponible.
+
+### Tiers
+
+!!!success
+**Obligatoire**
+!!!
+
+Indique les tiers impactés par la mise en œuvre de la bonne pratique.
+
+- Utilisateur/Terminal
+- Réseau
+- Datacenter
+
+### Bonnes pratique RGESN
+
+Permet de lier une bonne pratique du référentiel à mettre en œuvre à une ou plusieurs critères du RGESN.
+
+!!!warning Point d'attention
+C'est un champ libre, attention à avoir une consistance dans la manière de contribuer.
+!!!
+
+**Si activés :**
+
+- En contribution et en front, l'information est disponible.
+
+### Ressources sauvegardées
+
+!!!success
+**Obligatoire**
+!!!
+
+Indique les ressources (technique, abioptique, etc.) qui seront moins impactés si la bonne pratique est mise en œuvre.
+
+- Mémoire vive
+- Stockage
+- Réseau
+- Requêtes
+- Déchets électroniques
+- Consommation électrique
+- Émissions de gaz à effet de serre
+
+## Données annexes
+
+!!!success
+**Obligatoires**
+!!!
+
+- `trigramme`: Nom court du référentiel (ex: `RWEB`, `RWP`, etc.)
+- `currentVersion`: la version en cours. Utilisée dans le header et pour pré-remplir le champ version/RefID d'une fiche (a changer avant toute session de mise à jour) ;
+- `creationYear` : année de la création du référentiel. Utilisé dans le footer `creationYear - currentYear` ;
+- `refTitles[lang].short` : utilisés dans le header (ex: `Ecoconception web` ou `WordPress`) ;
+- `refTitles[lang].long` : utilisés dans title (par defaut) des pages (ex: `Référentiel de bonnes pratiques pour l'Ecoconception web` ou `Référentiel de bonnes pratiques pour WordPress`, `Référentiel de bonnes pratiques` est commun à tous les sites).
diff --git a/docs/contribution.md b/docs/contribution.md
@@ -0,0 +1,29 @@
+---
+label: Contribution
+icon: typography
+order: 20
+---
+
+# Comment contribuer
+
+## Prerequis
+
+Il faut 1 compte sur le CMS, et son URL. À demander au responsable.
+
+Lors de la première connexion, le CMS vous demandera de changer de mot de passe.
+
+## Navigation dans les contenus
+
+!!!warning
+Comme les contenus des référentiels sont différents, les captures d'écran peuvent ne pas être représentatif de la réalitées.
+!!!
+
+`TODO`
+
+## Contribution aux contenus
+
+!!!warning
+Comme les métadatas des référentiels sont différents, les captures d'écran peuvent ne pas être représentatif de la réalitées.
+!!!
+
+`TODO`
diff --git a/docs/informations.md b/docs/informations.md
@@ -0,0 +1,19 @@
+---
+label: Infos
+icon: info
+order: 5
+---
+
+# Informations
+
+## Contributeurs
+
+- :icon-paintbrush: **Design et UX** :
+  - [Florine Sueur :icon-mark-github:florinesueur](https://github.com/orgs/cnumr/people/florinesueur)
+- :icon-code: **Dévelopeurs** :
+  - [Renaud Héluin :icon-mark-github:hrenaud](https://github.com/orgs/cnumr/people/hrenaud)
+  - [Jean-Philippe Kha :icon-mark-github:hrenaud](https://github.com/orgs/cnumr/people/jpkha)
+
+## Contacts
+
+:icon-mail: contact@greenit.eco
diff --git a/docs/retype.yml b/docs/retype.yml
@@ -0,0 +1,30 @@
+input: .
+favicon: static/greenit_icone_intro-alt.png
+url: https://cnumr.github.io/lighthouse-plugin-ecoindex
+branding:
+  title: GenRefs
+  logo: static/greenit_icone_intro-alt.png
+  label: Green IT
+meta:
+  title: ' - Générateur de référentiels @ GreenIT'
+links:
+  - text: Association GreenIT
+    link: https://greenit.eco/
+    target: blank
+    icon: organization
+
+footer:
+  copyright: '&copy; Copyright {{ year }}. All rights reserved to GreenIT.eco'
+  links:
+    - text: License
+      link: ./licence.md
+      icon: shield
+    - text: Association GreenIT
+      link: https://greenit.eco/
+      target: blank
+      icon: organization
+edit:
+  repo: 'https://github.com/cnumr/best-practices-wordpress' # The URL to source files for this project
+  base: './docs' # Optional base path to a directory within repo
+  branch: 'main' # Point to a custom branch within the repo
+  label: 'Modifier sur GitHub' # A custom label for the generated link
diff --git a/docs/static/greenit_icone_intro-alt.png b/docs/static/greenit_icone_intro-alt.png
diff --git a/package.json b/package.json
@@ -3,6 +3,7 @@
   "version": "0.1.0",
   "private": true,
   "scripts": {
+    "doc": "cd docs && retype start",
     "dev": "tinacms dev -v -c \"next dev\"",
     "dev:prod": "TINA_PUBLIC_IS_LOCAL=false TINA_PUBLIC_REF_NAME=RWP NEXT_PUBLIC_REF_NAME=RWP tinacms dev -c \"next dev\"",
     "build": "TINA_PUBLIC_IS_LOCAL=false TINA_PUBLIC_REF_NAME=RWP NEXT_PUBLIC_REF_NAME=RWP tinacms build --partial-reindex && next build",
