Modifier et prévisualiser avec 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).

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

Lorsque vous enregistrez, la modification est prise en compte par Eleventy et s’affichera dans la prévisualisation en localhost sur votre navigateur.

---

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.

---

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/partenaire/home.njk
image:
    src: /img/partenaires/ign/ign-icon.png
    alt: Logo IGN
sidemenuNav: ign
---

• « title » correspond au titre de votre documentation partenaire.
• « layout » est un terme technique à mettre systématiquement.
• « image/src » 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.

Dans le fichier eleventy.config.js situé à la racine du projet, créez votre identifiant de navigation dans l’objet « sidemenuNavigations » à la suite des navigations préexistantes en vous basant sur le modèle de ces dernières :

const sidemenuNavigations = {
    "utilisateurNavigation": { navKey: "guides-utilisateur", title: "Guides utilisateur" },
    "developpeurNavigation": { navKey: "guides-developpeur", title: "Guides développeur" },
    "producteurNavigation": { navKey: "guides-producteur", title: "Guides producteur" },
    "ignNavigation": { navKey: "ign", title: "Institut national de l’information géographique et forestière" }
};

Vous pouvez ensuite créer un dossier du même nom que votre fichier .md dans le dossier « partenaires ». À la racine de ce dossier, créez un fichier .11tydata.js du même nom que le dossier. Dans ce fichier vous pourrez alors définir le paramètre « nav » sur la valeur de l’identifiant de navigation que vous avez créé, cela permet d’attribuer ce paramètre à toutes les pages de votre dossier afin qu’elles apparaissent toutes dans le même menu latéral. Par exemple dans le fichier ign.11tydata.js, on a :

eleventyNavigation: {
    nav: "ign",
},

---

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 :

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

---

Fichier .11tydata.js #

Chaque sous-dossier doit contenir un fichier « nom-du-dossier-parent.11tydata.js » qui permet de déterminer les paramètres communs des fichiers adjacents.

Ce fichier contient par exemple les informations suivantes (modifiez les « tags », « url », « title » et « parent » 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",
        },
    ],
    eleventyNavigation: {
        parent: "Créer des pages de documentation",
    },
};

• « tags » correspond aux tags communs à tous les fichiers adjacents.
• « segments/url » définit l’url de la page parent pour créer le lien vers cette dernière dans le fil d’arianne.
• « segments/title » indique le titre du lien de la page parent dans le fil d’arianne.
• « eleventyNavigation/parent » indique le parent commun de tous les fichiers adjacents. Ce qui permet que ces pages apparaissent sous ce parent dans le menu latéral.

---

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
description: Créer, modifier ou supprimer des pages
tags:
    - Rédaction
    - Modification
    - Github
    - Fork
    - Clone
eleventyNavigation:
    key: Rédiger sa documentation
    order: 3
pictogram: document/document.svg
summary:
    visible: true
    depth: 2
---

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 :

## Titre de niveau 1

### Titre de niveau 2

#### 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"]
    ]
}) }}

---

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.

---