complément documentation rédacteur

docs/markdown/cartouche.md

@@ -0,0 +1,103 @@
+# Cartouche d'en-tête des fichiers markdown pour Eleventy
+
+Le cartouche contient les métadonnées de la page et est situé immédiatement avant le contenu d'un fichier markdown et est délimité par 2 lignes de 3 tirets `---`.
+
+La syntaxe de la partie cartouche est de type `yaml`, c'est à dire constituée de lignes de la forme `clé: valeur` et où l'indentation, qui permet de hiérarchiser les informations, est importante.
+
+## Titre de la page
+
+```yml
+title: Titre de la page
+```
+
+NB: le titre étant mentionné dans le cartouche, il est inutile de le répéter dans le contenu. Le contenu ne devra donc pas commencer par une ligne débutant par un seul `#`.
+
+## Description
+
+```yml
+description: Une description de quelques mots ou quelques phrases de la page
+```
+
+La description apparait sur les pages comme un texte "chapeau", juste avant le contenu de la page.
+
+Elle est également présente dans une balise `<meta>` de la page, ce qui va être utile dans les résultats des moteurs de recherche ou en prévisualisation de la page sur les réseaux sociaux.
+
+## Date
+
+Par défaut, les pages du site sont datées du moment de leur dernière révision dans le dépôt.
+
+L'absence de précision dans le cartouche équivaut à :
+
+```yml
+date: git Last Modified
+```
+
+Il est possible de préciser une date "en dur", mais il est déconseillé de le faire sur toutes les pages. L'horodatage automatique est plus pratique.
+
+## Mots clés
+
+Les mots clés apparaissent en haut de page, sous le titre de la page.
+
+Ils servent également de filtres sur la page de résultats de recherche.
+
+```yml
+tags:
+    - Géoplateforme
+    - Découverte
+    - Tutoriel
+```
+
+Attention à utiliser toujours les mêmes mots clés. Eviter l'utilisation mélangée du pluriel et du singulier.
+
+## Fil d'ariane
+
+Il est d'usage qu'un fil d'ariane soit présent sur toutes les pages d'un site web. Ceci permet au visiteur de savoir facilement où il se situe dans l'arborescence du site et de pouvoir remonter vers les pages intermédiaires dans la hiérarchie.
+
+Le fil d'ariane commence toujours par un lien vers la page d'accueil et se termine par le titre de la page courante (non cliquable). Entre les 2 doivent se trouver des liens vers des pages intermédiaires dans la hiérarchie du site.
+
+Référence : https://www.systeme-de-design.gouv.fr/composants-et-modeles/composants/fil-d-ariane
+
+Pour un fil d'ariane de cette forme : `Accueil > Documentation producteur > Page courante`. Il suffit de décrire le segment intermédiaire :
+
+```yml
+segments:
+    - url: /producteur
+      title: Documentation producteur
+```
+
+## Menu latéral
+
+Dans le cas d'une page longue, il est possible d'ajouter un sommaire sous forme de menu latéral.
+
+```yml
+sidemenu: true
+```
+
+Le sommaire sera construit automatiquement à partir de la hiérarchie des titres de la page.
+
+## Exemple
+
+Page de tutoriel sans menu latéral avec 2 niveaux intermédiaires dans le fil d'ariane.
+
+```md
+---
+title: Contrôle des accès
+description: Authentification et accès à l'entrepôt et aux services de diffusion
+tags:
+    - Contrôle des accès
+    - Index des tutoriels
+segments:
+    - url: /developpeur
+      title: Documentation développeur
+    - url: /tutoriels
+      title: Tutoriels
+---
+
+Contenu de la page...
+```
+
+## Système d'héritage
+
+Il n'est pas nécessaire de répéter toutes les informations du cartouche sur toutes les pages. Si des propriétés sont identiques entre toutes les pages d'un même dossier `nom-du-dossier`, elles peuvent être écrites une seule fois dans un fichier `nom-du-dossier.11tydata.js` situé à la racine du dossier.
+
+Généralement le gabarit utilisé pour la mise en page ou une partie des mots clés sont partagés entre toutes les pages d'un même dossier.

docs/markdown/syntaxe.md

@@ -0,0 +1,152 @@
+## Syntaxe Markdown pour Eleventy
+
+Le contenu des pages du site est écrit dans les fichiers markdown à la suite du [cartouche](./cartouche.md).
+
+L'essentiel du contenu est écrit en syntaxe markdown de base qui permet d'écrire :
+
+- des paragraphes
+- des titres et sous-titres (lignes commençant par 2 `##.` ou plus)
+- du texte en gras `**texte**` ou en italique `*texte*`)
+- des listes
+- des [liens hypertextes](#les-liens)
+- des [images](#les-images)
+
+Référence : https://codegouvfr.github.io/eleventy-dsfr/fr/blog/md-cheatsheet/
+
+Bases d'écriture : https://commonmark.org/help/
+
+Cette syntaxe markdown de base ne suffit pas pour écrire des contenus riches en profitant de toutes les possibilités offertes par le Système de design de l'État (DSFR). C'est pourquoi des [composants](#composants) supplémentaires ont été créés pour étendre les possibilités.
+
+## Les liens
+
+La syntaxe markdown de base est la suivante :
+
+```md
+[texte du lien](cible du lien)
+```
+
+La cible du lien peut être une URL absolue (commençant par `https://...`) ou relative (vers une autre page du site). Dans ce cas il très facile de faire une erreur de chemin et la prévisualisation du site permet de vérifier que le lien fonctionne.
+
+Pour faire un lien qui ouvre un nouvel onglet.
+
+## Les images
+
+Les images sont à déposer dans un dossier de `public/img/` en utilisant une arborescence similaire à celle de `content`.
+
+Par exemple si la page que vous écrivez est dans `content/fr/tutoriels/decouverte`, les images sont à placer dans `public/img/tutoriels/decouverte`.
+
+Les images sont à nommer en minuscule (y compris l'extension), sans espaces (utilisez des tirets) ni caractères spéciaux et surtout avec un nom parlant.
+
+Par exemple `creation-fiche.png` plutôt que `image-2.png`.
+
+Les images doivent être adaptées à un usage écran. Au maximum, sur un gabarit qui n'a pas de menu latéral, elles peuvent occuper une largeur de **1200px**. Inutile de mettre des images plus grandes.
+
+Enfin le DSFR conseille des images avec des ratios précis, avec une préférence pour le 16:9.
+
+En 16:9 une image de 1200px de large fera 675px de hauteur par exemple.
+
+Une fois l'image créée dans le dossier public, elle peut être insérée dans le contenu de cette façon :
+
+```md
+![texte alternatif de l'image](/img/chemin/vers/image.png)
+```
+
+Le contenu devant être accessible, il est obligatoire de renseigner le texte alternatif de l'image.
+
+## Détails typographiques
+
+Quelques points d'attention pour améliorer la qualité des pages en général.
+
+### Espaces insécables
+
+On ne maitrise pas la résolution d'écran du visiteur final du site. La largeur de son écran (ou de la fenêtre de son navigateur) va générer des passages à la ligne que l'on ne peut pas maitriser totalement.
+
+Pour éviter les sauts de ligne avant les caractères de ponctuation double : `:`, `!`, `;`, `?` ; il est sage de les précéder d'un espace insécable, et donc d'écrire : `fin de la question ?` plutôt que `fin de la question ?`. Dans le navigateur, ` ` n'est pas visible et constitue un espace insécable, qui ne peut pas être remplacé par un passage à la ligne.
+
+### Majuscules accentuées
+
+Faire l'effort d'utiliser des majuscules accentuées même si le clavier azerty ne facilite pas la tâche. Par exemple pour écrire _État_ plutôt que _Etat_.
+
+### Apostrophes
+
+Utiliser de préférence une apostrophe `’` plutôt qu'une simple quote `'`. En tout cas éviter de mélanger les 2 sur une page.
+
+## 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'État, 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._
+
+### 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
+
+## Les balises HTML
+
+Il est possible d'utiliser des balises HTML au milieu du contenu markdown.
+
+Cela peut s'avérer nécessaire dans des cas très particuliers. Par exemple pour gérer finement les espacements entre les blocs de contenu.

docs/redacteur.md

@@ -29,26 +29,30 @@ Pour soumettre une demande ou un problème concernant le site de la documentatio
 
 ## Structure
 
-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.
+### Arborescence des dossiers
 
-A date, le site de la documentation n'est pas traduit en anglais et seule la partie en français `content/fr/` est enrichie.
+Tout le contenu du site se trouve dans le dossier `content`, sous forme de fichiers au format markdown (.md). Les fichiers de ce dossier sont ensuite transformés en pages HTML dans le dossier `_site` qui est absent du dépôt car généré seulement pour le déploiement.
+
+Les fichiers qui ne nécessitent pas de transformation pour être affichés dans un navigateur web se trouvent dans le répertoire `public`. C'est ici notamment que se trouvent les images qui illustrent la documentation.
+
+En tant que rédacteur, vous n'aurez généralement pas de modification à effectuer hors de ces 2 dossiers :
+
+- `content` et même uniquement `content/fr/` pour le contenu en français
+- `public`
 
 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.
 
 Documentation : https://codegouvfr.github.io/eleventy-dsfr/fr/blog/navigation/
 
-## Syntaxe Markdown
+### Structure d'un fichier Markdown
 
-Référence : https://codegouvfr.github.io/eleventy-dsfr/fr/blog/md-cheatsheet/
+Les fichiers markdown sont des fichiers au format texte, modifiables avec un logiciel éditeur de texte comme le _Bloc note_, _Notepad++_ ou _VS Code_ (conseillé).
 
-Bases d'écriture : https://commonmark.org/help/
+Le texte est découpé en 2 parties :
 
-## Composants
-
-De nombreux composants qui n'existent pas dans la syntaxe markdown standard sont disponibles pour enrichir le contenu des pages.
-
-Consultez [composants.md](composants.md).
+- [Une _en-tête_ ou _cartouche_](markdown/cartouche.md) qui contient les métadonnées de la page du site correspondant à ce texte
+- [Le corps du texte](markdown/syntaxe.md)
 
 ## Rédiger un tutoriel
 
@@ -64,7 +68,8 @@ Système de design de l'État : https://www.systeme-de-design.gouv.fr/
 
 ### Gestion des espacements
 
-Veiller à espacer les différents composants afin d'avoir un rendu facilement lisible. Le DSFR est restrctif sur les espacements, il propose des classes pour les effectuer :
+Veiller à espacer les différents composants afin d'avoir un rendu facilement lisible. Le DSFR est restrictif sur les espacements, il propose des classes pour les effectuer :
+
 - `.fr-mt-1w` margin top de 1w
 - `.fr-mb-1w` margin bottom de 1w
 - `.fr-my-1w` margin top et bottom de 1w
@@ -77,4 +82,4 @@ Stocker les images avec des noms explicites dans un dossier propre au tutoriel d
 
 ### Prettier
 
-Désactier Prettier car il peut causer des mauvaises modifications en Markdown.
+Désactiver Prettier car il peut causer des mauvaises modifications en Markdown.