documentation redacteur

README.md

@@ -1,22 +1,27 @@
 # cartes.gouv.fr-documentation
 
-Site de documentation statique associé à [cartes.gouv.fr](https://cartes.gouv.fr/) et aux services de la Géoplateforme.
+Ce dépôt constitue un site de documentation statique associé à [cartes.gouv.fr](https://cartes.gouv.fr/) et aux services de la Géoplateforme.
 
-Il est construit sur la base de [codegouvfr/eleventy-dsfr](https://github.com/codegouvfr/eleventy-dsfr).
+Il est construit sur la base des templates de [codegouvfr/eleventy-dsfr](https://github.com/codegouvfr/eleventy-dsfr) et sur le générateur de site statique [Eleventy](https://www.11ty.dev/).
 
 ## Prise en main
 
-[Documentation développeur](docs/developpeur.md)
+-   [Guide de contribution](CONTRIBUTING.md)
+-   [Principes généraux](docs/index.md)
+-   [Documentation rédacteur](docs/redacteur.md)
+-   [Documentation développeur](docs/developpeur.md)
 
-## Ajout de contenu
+## Déploiements
 
-[Documentation rédacteur](docs/redacteur.md)
+La branche `main` est automatiquement déployée sur github pages en quelques minutes à l'adresse : [https://ignf.github.io/cartes.gouv.fr-documentation](https://ignf.github.io/cartes.gouv.fr-documentation)
 
-## Déploiements
+Il faut ensuite un tag respectant le versioning sémantique (`vX.Y.Z`) pour qu'une image prête pour la production soit générée sur le registre ghcr.io avec une url de la forme :
 
-La branche `main` est automatiquement déployée sur github pages en quelques minutes.
+```
+ghcr.io/ignf/cartes.gouv.fr-documentation:vX.Y.Z
+```
 
-Il faut ensuite un tag respectant le versioning sémantique (`vX.Y.Z`) pour qu'une image prête pour la production soit générée sur le registre ghcr.io.
+Le déploiement de cette image n'est ensuite plus du ressort de ce dépôt.
 
 ## Licence
 

docs/composants.md

@@ -0,0 +1,83 @@
+# Composants
+
+Les composants que vous pouvez utiliser dans une documentation provenant de `codegouvfr/eleventy-dsfr`, ceux-ci sont documentés avec des exemples directement sur le site de démonstration https://codegouvfr.github.io/eleventy-dsfr/
+
+Ces composants sont basés sur le Système de Design de l'Etat, veuillez vous-y référer en cas de doute sur l'utilisation d'un composant. Notamment dans quel contexte il peut ou ne peut pas être utilisé.
+
+Enfin, n'hésitez pas à faire remonter des besoins via les issues : https://github.com/IGNF/cartes.gouv.fr-documentation/issues/new/choose
+
+## Accordéon
+
+Exemple : https://codegouvfr.github.io/eleventy-dsfr/fr/blog/accordeon/
+
+Référence : https://www.systeme-de-design.gouv.fr/elements-d-interface/composants/accordeon/
+
+## Alerte
+
+Exemple : https://codegouvfr.github.io/eleventy-dsfr/fr/blog/alerte/
+
+Référence : https://www.systeme-de-design.gouv.fr/elements-d-interface/composants/alerte
+
+### Carte
+
+Exemple : https://codegouvfr.github.io/eleventy-dsfr/fr/blog/carte/
+
+Référence : https://www.systeme-de-design.gouv.fr/elements-d-interface/composants/carte
+
+### Citation
+
+Exemple : https://codegouvfr.github.io/eleventy-dsfr/fr/blog/citation/
+
+Référence : https://www.systeme-de-design.gouv.fr/elements-d-interface/composants/citation
+
+### Evènement
+
+_Cette possibilité de eleventy-dsfr n'est pas utilisée._
+
+### Fil d'ariane
+
+Le composant fil d'ariane est utilisé sur la majorité des pages du site de documentation, il a été implémenté dans les gabarits.
+
+Pour qu'il soit effectivement présent sur une page, il faut prêter attention au remplissage de la section `segments` du cartouche, qui doit contenir le noms (`title`) et liens ()`url`) des pages "parentes".
+
+Exemple : https://codegouvfr.github.io/eleventy-dsfr/fr/blog/fil-d-ariane/
+
+Référence : https://www.systeme-de-design.gouv.fr/elements-d-interface/composants/fil-d-ariane
+
+### Mise en avant
+
+Exemple : https://codegouvfr.github.io/eleventy-dsfr/fr/blog/mise-en-avant/
+
+Référence : https://www.systeme-de-design.gouv.fr/elements-d-interface/composants/mise-en-avant
+
+### Retour en haut de page
+
+Exemple : https://codegouvfr.github.io/eleventy-dsfr/fr/blog/retour-en-haut-de-page/
+
+### Schéma
+
+Il est possible d'ajouter des illustrations raster (png, jpeg) ou vecteur (svg) ou d'utiliser la syntaxe `mermaid` pour insérer des schémas.
+
+NB : Le cartouche du fichier doit contenir : `mermaid: true` pour que le js de mermaid qui effectue la transformation du schéma en SVG soit inclus avec la page.
+
+````md
+```mermaid
+flowchart LR
+A[Hard] -->|Text| B(Round)
+B --> C{Decision}
+C -->|One| D[Result 1]
+C -->|Two| E[Result 2]
+```
+````
+
+### Tableau
+
+Exemple : https://codegouvfr.github.io/eleventy-dsfr/fr/blog/tableau/
+
+Référence : https://www.systeme-de-design.gouv.fr/elements-d-interface/composants/tableau
+
+### Tuile
+
+Exemple : https://codegouvfr.github.io/eleventy-dsfr/fr/blog/tuile/
+
+Référence : https://www.systeme-de-design.gouv.fr/elements-d-interface/composants/tuile

docs/index.md

@@ -0,0 +1,26 @@
+# Principes généraux
+
+Cette documentation explique comment est organisé le dépôt et quels sont les principes de son fonctionnement.
+
+## Un site web statique
+
+Ce dépôt permet de générer un site web statique, c'est à dire composé de pages web dont le contenu ne varie pas en fonction des caractéristiques de la demande. Un site statique fonctionne sans base de données.
+
+Comme il est toutefois peu aisé de rédiger du contenu sous forme de pages HTML directement, avec un système de balisage complexe, ce dépôt utilise un **générateur de site statique** qui va combiner des contenus rédigés dans un langage plus simple, le markdown, avec des gabarits de pages web, pour en faire des pages HTML qu'un serveur web pourra diffuser.
+
+Le générateur de site statique utilisé est [Eleventy](https://www.11ty.dev).
+
+Le site statique est parfois appelé "l'application" ou "le site" dans la suite.
+
+## Arborescence du dépôt
+
+-   `.docker` contient des fichiers de configuration pour conteneuriser l'application avec docker, pour en faire une "image docker" prête pour le déploiement.
+-   `.github` contient les templates des formulaires d'issues et les actions pour github (packager l'application, déployer sur github pages)
+-   `.husky` contient une instruction qui corrige la syntaxe des fichiers avant qu'ils soient commités (un "pre-commit hook")
+-   `.vscode` contient des informations de configuration pour l'éditeur Visual Studio Code
+-   `LICENSES` + `LICENSE.md` contient les textes des licences applicables à ce dépôt
+-   `_data` contient des données utiles sur l'ensemble du site, notamment des chaines traduites car eleventy gère l'internationalisation
+-   `_includes` contient les gabarits des pages et les squelettes des composants au format nunjucks (`.njk`)
+-   `content` contient presque tout le contenu du site, toutes ses pages, généralement au format markdown (`.md`) et plus exceptionnellement au format nunjucks
+-   `docs` contient la documentation relative au dépôt
+-   `public` contient les fichiers qui doivent être disponibles sur le site, sans êtres modifiés par eleventy (images, feuilles de styles,...). On les appelle aussi parfois `assets`.

docs/installation.md

@@ -18,28 +18,27 @@ Git et NodeJS sont indispensables pour aller plus loin dans l'installation.
 
 Sous Windows, après avoir installé _Git for Windows_, vous devriez avoir accès au clic droit dans l'explorateur à un menu contextuel "Git Bash here" qui vous permet de lancer une invite de commande qui est très adaptée à l'utilisation de Git et offre une bonne coloration syntaxique. Il est recommandé de la préférer à l'invite de commande par défaut de Windows.
 
-![alt text](image.png)
+![alt text](img/image.png)
 
-![alt text](image-1.png)
+![alt text](img/image-1.png)
 
 Les lignes de commandes qui suivent pourront être copiées, puis collées (`maj+Inser`) et executées (`Entrée`) dans l'invite de commande qui a été ouverte.
 
 ### Dupliquer le dépôt
 
 Il faut dupliquer le projet sur votre espace GitHub afin de pouvoir faire les changements de votre côté, les prévisualiser, puis les soumettre au dépôt principal.
 
-Dans le coin supérieur droit de la page, cliquez sur `Dupliquer` ou `Fork` puis `Create a new fork`. 
+Dans le coin supérieur droit de la page, cliquez sur `Dupliquer` ou `Fork` puis `Create a new fork`.
 
-![alt text](image-7.png)
+![alt text](img/image-7.png)
 
 Dans le champ `Description`, vous pouvez taper la description de votre duplication. Si vous le souhaitez, sélectionnez Copier la branche PAR DÉFAUT uniquement.
 
 Cliquez sur `Créer une duplication`.
 
 Votre clone du dépôt sera disponible sous l'URL https://github.com/votre_pseudo_github/cartes.gouv.fr-documentation. Vous bénéficiez alors d'un espace de travail qui vous est propre. Vous pourrez choisir de soumettre au dépôt principal seulement les éléments que vous choisissez.
 
-![alt text](image-8.png)
-
+![alt text](img/image-8.png)
 
 ### Cloner le dépôt
 

docs/redacteur.md

@@ -1,4 +1,4 @@
-# Documentation rédacteur 
+# Documentation rédacteur
 
 ## Installer le projet et le déployer localement
 
@@ -10,19 +10,18 @@ Voir [la documentation d'installation](installation.md).
 
 A la suite de l'installation de VS Code, vous pouvez prévisualiser l'écriture de contenu de plusieurs facons. Néanmoins, cette prévisualisation n'englobera pas les composants DSFR. Il faudra déployer le site en local pour avoir une image complète de prévisualisation.
 
-#### Dans la même fenêtre 
+#### Dans la même fenêtre
 
 `crtl+k` puis `V` ou cliquer sur le bouton de prévisualisation
 
-![alt text](image-2.png)
-![alt text](image-4.png)
+![alt text](img/image-2.png)
+![alt text](img/image-4.png)
 
 #### Dans un autre onglet de VS Code
 
 `Ctrl + Shift + V`
 
-![![alt text](image-6.png)](image-5.png)
-
+![![alt text](image-6.png)](img/image-5.png)
 
 ## Soumettre une contribution
 
@@ -32,7 +31,7 @@ Pour soumettre une demande ou un problème concernant le site de la documentatio
 
 Tout le contenu du site se trouve dans le répertoire `content`. En tant que rédacteur, aucune modification n'est généralement nécessaire dans d'autres répertoires.
 
-A date, le site de la documentation n'est pas traduit en anglais et seule  la partie en français `content/fr/` est enrichie. 
+A date, le site de la documentation n'est pas traduit en anglais et seule la partie en français `content/fr/` est enrichie.
 
 Le contenu de la barre de navigation principale n'est pas directement déterminée par l'arborescence des dossiers et fichiers mais par le contenu des cartouches de chaque fichier.
 Il est toutefois conseillé d'avoir une arborescence qui correspond à cette navigation pour faciliter le repérage.
@@ -47,99 +46,6 @@ Bases d'écriture : https://commonmark.org/help/
 
 ## Composants
 
-Les composants provenant de `codegouvfr/eleventy-dsfr` sont documentés avec des exemples directement sur le site de démonstration https://codegouvfr.github.io/eleventy-dsfr/
-
-Les composants ajoutés pour les besoins de la documentation de cartes.gouv.fr sont expliqués plus en détail ci-dessous.
-
-N'hésitez pas à faire remonter des besoins via les issues : https://github.com/IGNF/cartes.gouv.fr-documentation/issues/new/choose
-
-### Accordéon
-
-Exemple : https://codegouvfr.github.io/eleventy-dsfr/fr/blog/accordeon/
-
-Référence : https://www.systeme-de-design.gouv.fr/elements-d-interface/composants/accordeon/
-
-### Alerte
-
-```md
-{% from "components/component.njk" import component with context %}
-{{ component("alert", {
-    type: "info",
-    title: "Titre de l'info",
-    description: "<p>Le contenu de l'alerte</p>"
-}) }}
-```
-
-Si le type est omis, l'alerte sera de type `info`.
-
-Si le title est absent, il s'agira d'une alerte de petite taille, plus discrète.
-
-Les alertes ne peuvent pas avoir de bouton de fermeture.
-
-Référence : https://www.systeme-de-design.gouv.fr/elements-d-interface/composants/alerte
-
-### Carte
-
-Exemple : https://codegouvfr.github.io/eleventy-dsfr/fr/blog/carte/
-
-Référence : https://www.systeme-de-design.gouv.fr/elements-d-interface/composants/carte
-
-### Citation
-
-Exemple : https://codegouvfr.github.io/eleventy-dsfr/fr/blog/citation/
-
-Référence : https://www.systeme-de-design.gouv.fr/elements-d-interface/composants/citation
-
-### Evènement
-
-_Cette possibilité de eleventy-dsfr n'est pas utilisée._
-
-### Fil d'ariane
-
-Exemple : https://codegouvfr.github.io/eleventy-dsfr/fr/blog/fil-d-ariane/
-
-Référence : https://www.systeme-de-design.gouv.fr/elements-d-interface/composants/fil-d-ariane
-
-### Mise en avant
-
-Exemple : https://codegouvfr.github.io/eleventy-dsfr/fr/blog/mise-en-avant/
-
-Référence : https://www.systeme-de-design.gouv.fr/elements-d-interface/composants/mise-en-avant
-
-### Onglets
-
-_(à venir)_
-
-Référence : https://www.systeme-de-design.gouv.fr/elements-d-interface/composants/onglet
-
-### Retour en haut de page
-
-Exemple : https://codegouvfr.github.io/eleventy-dsfr/fr/blog/retour-en-haut-de-page/
-
-### Schéma
-
-Il est possible d'ajouter des illustrations raster (png, jpeg) ou vecteur (svg) ou d'utiliser la syntaxe `mermaid` pour insérer des schémas.
-
-NB : Le cartouche du fichier doit contenir : `mermaid: true` pour que le js de mermaid qui effectue la transformation du schéma en SVG soit inclus avec la page.
-
-````md
-```mermaid
-flowchart LR
-A[Hard] -->|Text| B(Round)
-B --> C{Decision}
-C -->|One| D[Result 1]
-C -->|Two| E[Result 2]
-```
-````
-
-### Tableau
-
-Exemple : https://codegouvfr.github.io/eleventy-dsfr/fr/blog/tableau/
-
-Référence : https://www.systeme-de-design.gouv.fr/elements-d-interface/composants/tableau
-
-### Tuile
-
-Exemple : https://codegouvfr.github.io/eleventy-dsfr/fr/blog/tuile/
+De nombreux composants qui n'existent pas dans la syntaxe markdown standard sont disponibles pour enrichir le contenu des pages.
 
-Référence : https://www.systeme-de-design.gouv.fr/elements-d-interface/composants/tuile
+Consultez [composants.md](composants.md).