Contribuer à la documentation TerriSTORY

Modifier une page

Modifier une page existante depuis GitLab

Il est possible de modifier une page existante directement depuis l'interface GitLab. On peut acceder à la page d'édition d'une page via le lien situé en haut à gauche de chaque page.

Une fois les modifications apportées, on peut les enregistrer en faisant un commit :

• Directement sur la branche main si on a les droits. Attention la modification sera automatiquement déployée.
• Vers une branche séparée si on n'a pas les droits sur la branche main ou que l'on ne souhaite pas déployer directement. On pourra ensuite faire une demande de fusion (merge request) vers la branche main.

La modification directement depuis GitLab est surtout adaptée aux petites modifications ou aux modifications qui ne nécessitent pas de prévisualisation.

Faire des modifications en local

Pour des modifications plus importantes (ajout de pages, mise en forme, images, icones...) il est préférable de travailler en local pour pouvoir prévisualiser les modifications en direct avant de les déployer.

• Cloner le dépôt GitLab
• Installer et déployer en local (instructions dans le README princial du dépôt)
• Faire les modifications nécessaires. Les modifications possibles sont décrites dans les sections suivantes. L'utilisation d'un éditeur de Markdown ou d'un IDE intégrant la syntaxe Markdown est conseillée.
• Commit les modifications puis les pousser sur le dépôt GitLab. Soit directement sur la branche main si on souhaite déployer directement. Soit sur une branche séparée que l'on pourra fusionner par la suite dans main pour déployer les modifications.

Fonctionnement des pages et de la navigation

Ce site est construit avec Material for Mkdocs, un framework de documentation qui permet de créer facilement des sites statiques sur la base de documents Markdown.

Vous pouvez consulter les documentations de Material for Mkdocs et de MkDocs pour découvrir toutes les fonctionnalités disponibles. Cette section présente les opérations les plus couramment utilisées.

Ajouter une nouvelle page

1. Créer un nouveau document Markdown

Ajouter un nouveau document Markdwon (en .md) dans l'arborescence du dossier docs/. Le nom du document et son emplacement dans l'arborescence définissent l'url associée à ce docuement.

Par exemple, un fichier docs/regions/auvergne-rhone-alpes/chaleur-renouvelable/potentiel-geothermie.md sera accessible à l'url <base_url>/regions/auvergne-rhone-alpes/chaleur-renouvelable/potentiel-geothermie

2. Ajouter le nouveau document à la navigation.

Le document est déjà accessible via l'url définie par son nom et son emplacement. Cependant pour rendre visible la nouvelle page dans la navigation du site il est nécessaire de l'ajouter à la configuration de la navigation.

La hierarchie de la navigation est définie dans le fichier mkddocs.yml dans la section nav. Pour ajouter la page à l'arborescence, on ajoute le lien du document .md (relatif par rapport à /docs) à l'emplacement souhaité.

mkdocs.yaml

nav:
  - Accueil: index.md
  - Guides d'utilisation: helps.md
  - Régions:
      - regions/index.md
      - Auvergne-Rhône-Alpes:
          - regions/auvergne-rhone-alpes/index.md
          - Chaleur renouvelable:
              - regions/auvergne-rhone-alpes/chaleur-renouvelable/besoins-industriels-en-chaleur.md
              - regions/auvergne-rhone-alpes/chaleur-renouvelable/potentiel-geothermie.md
      - Bretagne: regions/bretagne.md
    ...

La page potentiel-geothermie.md est maintenant visible dans la navigation du site. Le nom de la page dans la navigation peut être précisé

Le nom affiché par défaut est basé sur le titre de niveau 1 (#) du document ou son nom. Ce nom peut être modifié si nécessaire via l'attribut metadata "title" ou en précisant un nom directement dans nav :

mkdocs.yaml

- Chaleur renouvelable:
    - regions/auvergne-rhone-alpes/chaleur-renouvelable/besoins-industriels-en-chaleur.md
    - Le potentiel géothermie: regions/auvergne-rhone-alpes/chaleur-renouvelable/potentiel-geothermie.md

Il est possible de créer une "page de garde" pour une section en la nommant index.md et en la plaçant sous la section. C'est le cas de la page regions/index.md dans l'exemple ci dessus.

Note

De manière générale on essaiera de garder une arborescence similaire entre le dossier docs/ et la navigation (nav dans mkdocs.yml).

Cependant rien n'empêche dans nav de pointer vers un document qui n'est pas à l'emplacement équivalent dans docs/. On peut ainsi intégrer par exemple une page du socle commun dans une section régionale.

Rédiger une page en Markdown

Les pages utilisent le format Markdown. Quelques spécificités propre à MkDocs peuvent être retrouvée ici.

Material for MkDocs ajoute encore plus de possibilités de mise en forme qui sont toutes présentées ici.

Voici une liste non exhaustive des possibilités :

• Faire des liens vers d'autres pages : page régions (Attention à utiliser un lien relatif !)

Point d'attention

Des blocs de texte pour mettre en avant des informations.

Des annotations (1), tooltips :

1. Pour apporter des précisions

Des liens sous la forme de boutons

# Des blocs de code
import pandas as pd

Une organisationPar onglets

Contenu onglet 1

Contenu onglet 2

Des	tables
2	3
4	5

• Des diagrammes mermaid :

graph LR
  A[Start] --> B{Error?};
  B -->|Yes| C[Hmm...];
  C --> D[Debug];
  D --> B;
  B ---->|No| E[Yay!];

• Plus de 10000 icones : , , , , , ...

Des images avec des légendes

Note

Les liens vers les images doivent être des liens relatifs. Les images sont généralement stockées dans le dossier docs/assets/ mais peuvent également être stockées plus proche du document .md ou provenir d'une url externe.

• Des notations mathématiques \(f(a)=f(b)\) :

\[ \cos x=\sum_{k=0}^{\infty}\frac{(-1)^k}{(2k)!}x^{2k} \]

• Des définitions d'abbréviations : PCAET