Cette page explique la procédure pour créer, modifier ou supprimer des pages de documentation pour les partenaires.

1 - Prévisualisation sur VS Code #

À 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 (cf. page précédente).

1.1 - Dans la même fenêtre VS Code #

Cliquez sur le bouton de prévisualisation (ou utilisez les raccourcis claviers « crtl+k » puis « V ») :

1.2 - Dans un autre onglet de VS Code #

Utilisez les raccourcis clavier « Ctrl + Shift + V »

2 - Effectuer des modifications #

2.1 - Modifier des fichiers #

Il vous suffit d’éditer, de créer ou de supprimer les fichiers dans votre dossier. Lorsque vous enregistrez, la modification est prise en compte par Eleventy et s’affichera dans la prévisualisation en localhost sur votre navigateur.

2.2 - Structure #

2.2.1 - Emplacement des modifications #

En tant que rédacteur, vous n’aurez généralement pas de modification à effectuer hors de ces deux dossiers :

• « content » et même uniquement « content/fr/ » pour le contenu en français. Ce dossier contient le contenu des pages 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.
• « public » qui contient les fichiers ne nécessitant pas de transformation pour être affichés dans un navigateur web (notamment les images).

Le contenu de la barre de navigation n’est pas directement déterminée par l’arborescence des dossiers et fichiers mais par le contenu des cartouches (ou en-têtes) de chaque fichier. Il est toutefois conseillé d’avoir une arborescence qui corresponde à cette navigation pour faciliter le repérage.

2.2.2 - Nouveau partenaire #

Pour ajouter un nouveau partenaire à la documentation, il faut ajouter un fichier .md dans le dossier « partenaires », contenant les informations suivantes :

---
title: Institut national de l’information géographique et forestière
layout: layouts/accueil.njk
image:
    path: ../../../cartes.gouv.fr-documentation/public/img/partenaires/ign.png
    alt: Logo IGN
sidemenuNav: ign
---

• « title » correspond au titre de votre documentation partenaire.
• « layout » est un terme technique à mettre systématiquement.
• « image/path » indique le chemin de l’image à ajouter à la card partenaire. L’image doit être déposée dans « cartes/gouv.fr-documentation/public/img/partenaires/ ».
• « image/alt » indique la description alternative de l’image.
• « sidemenuNav » correspond à l’identifiant de navigation au sein de cette documentation partenaire. Cet identifiant devra être indiqué dans les en-têtes des pages filles (voir paragraphe ......) et dans les fichiers .js décrits ci-après.

Dans le fichier eleventy.config.js situé à la racine du projet, en remplaçant « ign » par l’identifiant de navigation partenaire déterminé :

eleventyConfig.addCollection("ignNavigation", function (collectionApi) {
    return collectionApi.getAll().filter((item) => {
        return item.data.eleventyNavigation && item.data.eleventyNavigation.nav === "ign";
    });
});

Dans le fichier accueil.njk situé dans « _includes/layouts », en remplaçant « ign » par l’identifiant de navigation partenaire déterminé et en indiquant le titre de la documentation partenaire :

{% elif effectiveNav == "ign" %}
    {% set navLinks = collections.ignNavigation | filterCollectionLang | eleventyNavigation %}
    {% set navCollection = collections.ignNavigation %}
    {% set sidemenuTitle = "Institut national de l’information géographique et forestière" %}

Dans le fichier article.njk situé dans « _includes/layouts », en remplaçant « ign » par l’identifiant de navigation partenaire déterminé et en indiquant le titre de la documentation partenaire :

{% elif eleventyNavigation.nav == "ign" %}
    {% set navLinks = collections.ignNavigation | filterCollectionLang | eleventyNavigation %}
    {% set sidemenuTitle = "Institut national de l’information géographique et forestière" %}

Dans le fichier parent.njk situé dans « _includes/layouts », en remplaçant « ign » par l’identifiant de navigation partenaire déterminé et en indiquant le titre de la documentation partenaire :

{% elif eleventyNavigation.nav == "ign" %}
    {% set navLinks = collections.ignNavigation | filterCollectionLang | eleventyNavigation %}
    {% set navCollection = collections.ignNavigation %}
    {% set sidemenuTitle = "Institut national de l’information géographique et forestière" %}

2.2.3 - Fichier .md parent #

Chaque dossier doit contenir un fichier .md pour chacun de ses sous-dossiers, portant le même nom que celui-ci :

Ce fichier correspond à la page d’accueil de ce sous-dossier. Il définit via son en-tête l’arborescence du dossier dans la navigation. L’en-tête de ce fichier peut être différent suivant deux cas :

Cas n°1 : le sous-dossier correspondant se situe au premier niveau du menu latéral. Dans ce cas il faut écrire l’en-tête comme suit :

---
title: Créer des pages de documentation
layout: layouts/parent.njk
description: Création, modification et publication de documentation partenaire sur le site de documentation de Cartes.gouv.fr
tags: - Documentation - Partenaire
eleventyNavigation:
key: Créer des pages de documentation
order: 3
nav: guides-producteur
pictogram: "document/document-add.svg"
---

Cas n°2 : le sous-dossier correspondant se situe au deuxième ou au troisième niveau du menu latéral. Dans cas il faut ajouter un élément « parent » dans la partie « eleventyNavigation » :

---
title: Sous-dossier de niveau 2
layout: layouts/parent.njk
description: Description du sous-dossier de niveau 2
tags: - Documentation - Partenaire
eleventyNavigation:
key: Sous-dossier de niveau 2
order: 1
nav: guides-producteur
parent: Créer des pages de documentation
pictogram: "document/document-add.svg"
---

Enfin, l’élément « nav » dépend de l’emplacement du sous-dossier :

• Au sein d’un des trois guides utilisateur, producteur, développeur : « guides-utilisateur », « guides-producteur » ou « guides-développeur ».
• Au sein d’une documentation partenaire : indiquez le même identifiant que l’élément « sidemenuNav » indiqué dans l’en-tête de la page d’accueil partenaire.

2.2.4 - Fichier .11data.js #

Chaque sous-dossier doit contenir un fichier « nom-du-dossier-parent.11tydata.js » qui permet de déterminer l’arborescence des fichiers adjacents.

Ce fichier contient les informations suivantes (modifiez les « tags », « url » et « title » pour correspondre à votre page) :

module.exports = {
    tags: ["Documentation", "Partenaire"],
    segments: [
        {
            url: "/guides-producteur/creer-des-pages-de-documentation",
            title: "Créer des pages de documentation",
        },
    ],
};

2.2.5 - Fichier .md décrivant le contenu de la page #

Le texte est découpé en 2 parties : un en-tête (ou cartouche) qui contient les métadonnées de la page du site correspondant à ce texte, et le corps du texte. L’en-tête est similaire à celui des pages parents :

## 
title: Rédiger sa documentation
tags: - Rédaction - Documentation - Modification - Github - Fork - Clone
eleventyNavigation:
key: Rédiger sa documentation
parent: Créer des pages de documentation
order: 3
nav: guides-producteur
pictogram: document/document.svg

---

Si des éléments njk (nunjucks) sont utilisés dans la page (par exemple pour afficher une image, un extrait de code, etc.) alors il faut rajouter la ligne suivante après l’en-tête :

{% from "components/component.njk" import component with context %}

Le contenu des pages de documentation est rédigé en markdown (.md), éditables avec un logiciel éditeur de texte comme le Bloc note, Notepad++ ou VS Code (conseillé).

La syntaxe propre au mardown est relativement simple. Ci-dessous vous pouvez retrouver les différentes syntaxes à utiliser :

## 1 - Titre de niveau 1

### 1.1 - Titre de niveau 2

#### 1.1.1 - Titre de niveau 3

**texte en gras**
_texte en italique_

- liste à puces
- liste à puces

:::info
Contenu de la bulle info
:::

:::warning
Contenu de la bulle warning
:::

:::callout
Contenu du bloc grisé
:::

Pour afficher un lien s’ouvrant dans la même fenêtre :

[Nom du lien url](https://monurl.fr)

Pour afficher un lien s’ouvrant dans une nouvelle fenêtre :

<a href="https://lien-url.com" target="_blank" rel="noopener noreferrer" title="Titre à afficher au survol - ouvre une nouvelle fenêtre"
    >Titre à afficher dans le texte</a
>

Pour afficher une image :

![Description de l’image](/img/partenaires/producteurABC/.../monImage.png){.fr-responsive-img .frx-border-img .frx-img-contained}

Pour afficher un extrait de code :
    ```njk
    {% raw %}
        contenu du code
    {% endraw %}
    ```

Pour afficher un tableau
{{ component("table", {
    headers: ["Titre 1", "Titre 2", "Titre 3"],
    data: [
        ["cellule 1.1", "cellule 1.2", "cellule 1.3"],
        ["cellule 2.1", "cellule 2.2", "cellule 2.3"],
        ["cellule 3.1", "cellule 3.2", "cellule 3.3"]
    ]
}) }}

2.4 - Images et pictogrammes #

Les images sont stockées dans le dossier « cartes.gouv.fr-documentation/public/img/partenaires/producteurABC/... ». Il suffit de rajouter votre image dans le dossier correspondant.

Il existe une liste de pictogrammes réutilisables dans le dossier « cartes.gouv.fr-documentation_site\artwork\pictograms ». Pour appeler un pictogramme existant dans l’en-tête, il suffit d’indiquer le dossier parent de l’en-tête et son nom :

Il est possible de créer ses propres pictogrammes customisés. Il faut alors respecter les recommandations du DSFR : Pictogramme - Système de Design de l'État

Placez votre pictogramme .svg dans le dossier « cartes.gouv.fr-documentation\public\artwork\pictograms\custom », et appelez le pictogramme dans l’en-tête avec « custom/nomDuPictogramme.svg ».

---

Vous savez maintenant tout ce qu’il faut savoir pour modifier votre documentation ! Rendez-vous page suivante pour faire le point sur les bonnes pratiques rédactionnelles à respecter pour rédiger votre documentation.

---