YAML pour la configuration#

Introduction#

Les fichiers de configuration du site mkdocs.yml et ci.yml sont écrits en YAML, un langage avec une syntaxe la plus lisible possible par des humains pour représenter des données.

Aussi ce langage est largement utilisé par ailleurs comme par exemple en domotique pour la configuration du logiciel Home Assistant :

capture configuration.yaml — exemple d’un fichier configuration.yaml pour Home Assistant

Notions de YAML utiles#

Les données sont sous la forme clé: valeur, à raison d'un couple par ligne ;
```
nom: toto
```
Les commentaires sont signalés par le signe dièse # et se prolongent sur tout le reste de la ligne ;
```
# Commentaire
salut: "Degemer mat" # Commentaire : bienvenue en Breton !
```
Il est pratique de placer un # au début d'une ligne pour désactiver sa prise en compte ;

Dans Visual Studio Code, la combinaison de touches Ctrl＋/ active/désactive une ligne de code...

Les imbrications de la structure de données (tableau associatif, dictionnaire) sont assurées par l'indentation :

mon_dictionnaire:
    propriete_1: valeur  
    propriete_2: valeur
# ou
mon_dictionnaire_bis: {propriete_1: valeur, propriete_2: valeur }
# Comme en Python ? En fait, c'est au format JSON que YAML accepte.

Les éléments d'une liste (tableau) sont dénotés par le tiret -, suivi d'une espace, à raison d'un élément par ligne :

ma_liste:
- a
- b
- c
# ici l'indentation n'a pas d'importance
# ou
ma_liste_bis: [a,b,c]
# Comme en Python ? En fait, c'est au format JSON que YAML accepte.

Toute valeur qui ne peut être convertie ni en entier, ni en nombre à virgule flottante, ni en tout autre type reconnu par YAML est interprétée comme une chaine de caractères.
Pour éviter les situations ambiguës, les valeurs de type chaine de caractères (string) peuvent être entourés de guillemets doubles ", ou simples ' :
```
key: "1234"
```
Les valeurs booléennes sont true ou false (de préférence...) ;
Un ~ représente une valeur NULL ;

Un > permet d'écrire sur plusieurs lignes une valeur longue sans conserver les retours à la ligne :

site_description: >
    Tutoriel pour créer et gérer un site web depuis un dépôt git 
    avec le framework material pour mkdocs et des notebook jupyter

Ressources pour aller plus loin avec YAML : ...

Le fichier `ci.yml`#

Le fichier ci.yml doit être placé dans une arborescence de répertoires nommés .github/workflows/ci.yml.

Les données qu'il contient sont destinées à configurer le bot de GitHub avec toutes les applications logicielles, les plugins MkDocs et les extensions MarkDown, nécessaires pour qu'il puisse créer et mettre à jour automatiquement¹ la branche gh-pages à partir du contenu de la branche main à chaque changement (commit + push).

Exemple pour ce site : ...

name: ci
on:
  push:
    branches:
    - main
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
        with:
        python-version: 3.x      
      - run: pip install --upgrade pip
      - run: pip install mkdocs-material
      - run: pip install mkdocs-jupyter
      # C'est ici qu'il faut ajouter si besoin
      # les instructions pour installer avec pip
      # les autres plugins MkDocs ou extensions MarkDown
      # souhaités pour le déploiement du site...

      - run: mkdocs gh-deploy --force

Ce code correspond à celui proposé dans la documentation MkDocs-Material si ce n'est :

la suppression de l'item - master car la branche par défaut du projet est ici la branche main ;
l'ajout de l'item - run: pip install mkdocs-jupyter qui installe le plugin mkdocs-jupyter pour ajouter directement des fichiers .ipynb et .py comme nouvelles pages du site...

Le fichier `mkdocs.yml`#

Les données de ce fichier définissent la configuration du site web afin de personnaliser son style, son organisation, ses fonctionnalités et son comportement...

Configuration minimale#

Au minimum, ce fichier de configuration pour MkDocs doit contenir les deux paramètres :

site_name: une chaine de moins de 70 caractères définissant le titre du site qui s'affichera dans l'onglet du navigateur :

Exemple extrait du fichier mkdocs.yml de ce site : ...

Ce code YAML :génère le code HTML :

site_name: ADN - Tutoriel site web

<head>
    <title>ADN - Tutoriel site web</title>
</head>

site_url: l'adresse web principale de publication du site :

Exemple extrait du fichier mkdocs.yml de ce site : ...

Ce code YAML :génère le code HTML :

site_url: https://ericecmorlaix.github.io/adn-Tutoriel_site_web/

<head>
    <link rel="canonical" href="https://ericecmorlaix.github.io/adn-Tutoriel_site_web/">
</head>

Une explication en vidéo par Fred LELEU :

Les vidéos de Fred LELEU

Tous les autres paramètres sont facultatifs mais ils apportent des fonctionnalités intéressantes...

Dépôt#

repo_url: ajoute en haut à droite de chaque page du site, icône, nom et lien vers le dépôt GitHub du projet.
repo_name: personnalise le nom générique "GitHub" donné par défaut au lien vers le dépôt GitHub du projet.
edit_uri: complément au chemin pour aller depuis la valeur de repo_url: jusqu'au répertoire docs ;
Ce qui permet avec MkDocs-Material d'ajouter un bouton (crayon) d'édition du code source.md d'une page du site depuis le navigateur :
- edit/main/docs/ permet l'édition moyennant une connexion ;
- blob/main/docs/ comme tree/main/docs/ donne un accès anonyme en lecture.

Exemple extrait du fichier mkdocs.yml de ce site : ...

repo_url: https://github.com/ericECmorlaix/testMkDocsAdN/
repo_name: adn-Tutoriel_site_web
edit_uri: edit/main/docs/

Métadonnées#

On peut configurer l'ajout de métadonnées de description, moins de 300 caractères, et d'auteur pour toutes les pages du site :

Exemple extrait du fichier mkdocs.yml de ce site : ...

Ce code YAML :génère le code HTML :

site_description: >
    Tutoriel pour créer et gérer un site web depuis un dépôt git
    avec le framework material pour mkdocs et des notebook jupyter
site_author: "Eric MADEC"

<head>
    <meta name="description" content="Tutoriel pour créer et gérer un site web depuis un dépôt git avec le framework material pour mkdocs et des notebook jupyter">      
    <meta name="author" content="Eric MADEC">
</head>

Spécifier des métadonnées pour une page en particulier : ...

Il faut activer dans le fichier mkdocs.yml l'extension meta :

markdown_extensions:
    - meta

On peut alors ajouter dans l'en tête d'un fichier source.md :

un titre spécifique qui ne s'affichera dans l'onglet du navigateur que pour cette page ;
une description différente de celle commune aux autres pages du site.

Exemple extrait du fichier source MarkDown-Mkdocs_Material.md de ce site : ...

Ce code YAML dans l'en tête du fichier MarkDown :génère le code HTML :au lieu du code HTML :

---
description: Page en Français décrivant l'utilisation du MarkDown de MkDocs avec le thème Material pour produire une documentation web.
title: Le MarkDown avec Mkdocs-Material
---
## Introduction

<head>
    <meta name="description" content="Page en Français décrivant l'utilisation du MarkDown de MkDocs avec le thème Material pour produire une documentation web.">
    <title>Le MarkDown avec Mkdocs-Material - ADN - Tutoriel site web</title>
</head>

<head>
    <meta name="description" content="Tutoriel pour créer et gérer un site web depuis un dépôt git avec le framework material pour mkdocs et des notebook jupyter">
    <title>MarkDown Mkdocs-Material, le contenu - ADN - Tutoriel site web</title>
</head>

Par ailleurs l'activation de l'extension meta permet aussi d'activer/désactiver l'affichage du menu de navigation latéral et/ou de la table des matières

C'est le cas de la page d'accueil de ce site : ...

---
hide:
  - navigation
  - toc
---
Ceci est un tutoriel pour déployer un site web depuis un dépôt git
 avec le framework material pour mkdocs en incluant, ou pas, des notebook jupyter...

[![building_websites](https://ericecmorlaix.github.io/adn-Tutoriel_site_web/images/undraw_building_websites_i78t.svg){: align=right width=53%}](https://undraw.co/illustrations "Illustration par unDraw"){target="_blank"}


???+ adncogs "Créer, déployer puis maintenir son site :"

    1. [Premiers pas depuis un navigateur web](./PremiersPas) ;

    2. [Puis sur PC avec Visual Studio Code](./PCW10-VSC) ;

    3. [Et même sur un iPad en ligne de commande](./iPad.md) ;

![Bienvenue](https://ericecmorlaix.github.io/adn-Tutoriel_site_web/images/undraw_handcrafts_welcome.svg "Degemer Mat !"){width=20% .center }

???+ adncode "Coder pour générer ses pages web  :"

    1. [MarkDown Mkdocs-Material pour le contenu](./MarkDown-Mkdocs_Material.md) ;

    2. [YAML pour la configuration](./Yaml.md) ;

    3. [$\LaTeX$ pour les sciences](./LaTeX.md) ;

    4. [Python pour les macros](./Python.md) ;

Ajouter des métadonnées ou d'autres balises personnalisées : ...

Pour inclure des balises customisées entre les balises <head></head> d'une ou de toutes les pages du site, il faut créer à la racine du projet dans un dossier nommé overrides un fichier main.html et déclarer ce dossier en tant que custom_dir: dans le paramétrage de theme:...

L'organisation et le contenu du menu principal de navigation du site sont définis par la valeur associée au paramètre nav:.

Tous les chemins menant aux fichiers à inclure dans cette navigation doivent être relatifs à la valeur de la clé docs_dir qui est le dossier docs par défaut.

On peut également inclure des liens absolus vers des sources externes.

Exemple extrait du fichier mkdocs.yml de ce site : ...

# Dossier source, chemin relatif au fichier mkdocs.yml
docs_dir: docs
# Structure du menu principal de navigation, chemins relatifs au dossier source docs_dir
nav: 
- Accueil: index.md
- Créer, déployer puis maintenir son site:
    Dans un navigateur: PremiersPas.md
    Sur PC avec Visual Studio Code: PCW10-VSC.md
    Sur iPad en ligne de commande: iPad.md
- Coder pour générer ses pages web:
    MarkDown Mkdocs-Material, le contenu: MarkDown-Mkdocs_Material.md
    YAML, la configuration: Yaml.md
    LaTeX, les sciences: LaTeX.md
    Python, les macros: Python.md
- Ressources : Ressources.md

Une explication en vidéo par Fred LELEU :

Les vidéos de Fred LELEU

Remarque :

Toutes les fichier.md non répertoriés dans la configuration de navigation seront toujours convertis et inclus dans le site construit, cependant, les pages ainsi générées ne seront pas liées à partir de la navigation globale et ne seront pas incluses dans les liens de navigation en fin de page Précédent et Suivant. Ces pages resteront "cachées" à moins qu'elles ne soient directement associées à un lien hypertexte comme c'est le cas dans ce site pour la page iSH Shell. Néanmoins, on les trouve très facilement grace à la barre de recherche

Thème#

Il suffit de changer la valeur de la clé name: pour changer radicalement l'allure d'un site de documentation.
MkDocs inclut deux thèmes de base mais de nombreux autres thèmes existent qu'il suffit d'essayer...

Le choix du thème nommé material permet de préciser des paramètres imbriqués de configuration tels que :

les couleurs ;
les polices de caractères ;
la langue ;
les icônes ;
la navigation ;

Exemple extrait du fichier mkdocs.yml de ce site : ...

theme:
    name: material # autres thèmes : https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes
    custom_dir: overrides #  
    font: false  # RGPD ; pas de fonte Google
    language: fr # français
    logo: images/LogoIO.png # image qui apparait dans l'en tête à gauche du titre de la page
    # et qui est support du lien qui renvoie à la racine du site depuis toutes les pages
    favicon: images/LogoIO-pink.png # image qui apparait dans l'onglet du navigateur avant le titre du site
    # Palettes de couleurs jour/nuit, cf : https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/
    icon:
      repo: fontawesome/brands/github-alt # modifie l'icône du lien vers le dépot du projet de l'en tête
    palette: 
      - scheme: default # nom du thème clair
        primary: pink # couleur primaire des titres, des liens, ..., à prendre dans la liste
        accent: cyan # couleur d'accentuation au survol des boutons, desliens, ..., à prendre dans la liste
        toggle: # définition du bouton pour switcher de palette
          icon: material/weather-sunny # apparence
          name: Basculer en mode sombre # message
      - scheme: slate # nom du thème sombre
        primary: cyan
        accent: pink
        toggle:
          icon: material/weather-night
          name: Basculer en mode clair
    # Configuration du comportement de la navigation, cf : https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/
    features: 
        - navigation.instant # active XHR https://fr.wikipedia.org/wiki/XMLHttpRequest
        - navigation.tabs # Menu de navigation horizontal sous l'en-tête sauf sur appareil mobile
        # - navigation.tabs.sticky # Menu de navigation horizontal collant
        - navigation.top # bouton pour remonter tout en haut de la page
        - toc.integrate # Table Of Content, table des matières intégrée dans la barre verticale de navigation
        - header.autohide # masquage automatique de l'en tête du site lorsque l'on descend dans la page

Extensions MarkDown :#

Il s'agit principalement des extensions à déclarer pour autoriser les fonctions de balisage présentées à la page MarkDown Mkdocs-Material.

Exemple extrait du fichier mkdocs.yml de ce site : ...

markdown_extensions: # https://squidfunk.github.io/mkdocs-material/reference/abbreviations/
    # extensions de la bibliothèque markdown standard
    - abbr                          # Infobulles sur abbréviations 
    - meta                          # Métadonnées
    - def_list                      # Listes de définition.
    - attr_list                     # Sélecteurs CSS et attributs HTML personnalisés
    - md_in_html                    # Pour écrire en MarkDown dans des balises HTML https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#markdown-in-html
    - footnotes                     # Notes[^1] de bas de page.  [^1]: ma note.
    - admonition                    # Boite d'avertissements  !!! info "ma remarque"
    - toc:                          # Configuration de la table des matières générée automatiquement à partir des titres du niveau 2
        permalink: "&num;"          # Ajoute un symbole lien hypertexte vers l'ancre du titre #le-titre 
        toc_depth: 4                # Limite de la profondeur d'inclusion des titres dans la table des matières
    # extensions de python-markdown https://facelessuser.github.io/pymdown-extensions/
    - pymdownx.details              # plier/déplier les avertissements.
    - pymdownx.caret                # texte ^^souligné^^ ou en ^exposant^.
    - pymdownx.mark                 # texte ==surligné==.
    - pymdownx.tilde                # texte ~~barré~~ ou en ~indice~.
    - pymdownx.critic               # Pour du marquage et commentaires de révision de texte
    - pymdownx.highlight            # Coloration syntaxique du code
    - pymdownx.inlinehilite         # pour  `#!python  <python en ligne>`
    - pymdownx.snippets             # Inclusion de fichiers externe.
    - pymdownx.tasklist:            # Cases à cocher  - [ ]  et - [x]
        custom_checkbox:    true    #   avec cases d'origine
        clickable_checkbox: true    #   et cliquables.
    - pymdownx.tabbed               # Onglets coulissants.  === "Onglet"
    - pymdownx.superfences          # Imbrication de blocs.
    - pymdownx.keys:                # Touches du clavier.  ++ctrl+d++
        separator: "\uff0b"
    - pymdownx.emoji:               # Émojis  :boom:
        emoji_index: !!python/name:materialx.emoji.twemoji
        emoji_generator: !!python/name:materialx.emoji.to_svg
    - pymdownx.arithmatex:          # Formules en LaTeX 
        generic: true
        smart_dollar: false

Plugins#

Recherche#

On peut ajouter et configurer un plugin pour inclure une barre de recherche.

MkDocs-Jupyter#

En activant le plugin mkdocs-jupyter dans le fichier de configuration mkdocs.yml, tous les fichiers .ipynb et .py placés dans le dossier docs seront convertis en page web de la même facon qu'un fichier source.md.
Ces pages peuvent alors être déclarées dans la configuration de la stucture de navigation.

Différentes options existent autre que include_source: True qui crée une copie du fichier source.ipynb (ou .py) dans le dossier de la page sur le site pour permettre son téléchargement.

Pour afficher un bouton de téléchargement du fichier source.ipynb (ou .py) et obtenir un style d'affichage proche de l'affichage classique d'un notebook, il faut créer à la racine du projet dans un dossier nommé overrides un fichier main.html et déclarer ce dossier en tant que custom_dir: dans le paramétrage de theme:.

dans mkdocs.ymldans overrides/main.html

nav:
- Accueil: index.md
- Notebook: notebook.ipynb
- Python: python_script.py

plugins:
- mkdocs-jupyter:
    include_source: True

{% extends "base.html" %}    
{% block content %}
{% if page.nb_url %}
    <a href="{{ page.nb_url }}" title="Download" class="md-content__button md-icon">
        {% include ".icons/material/download.svg" %}
    </a>
{% endif %}
{{ super() }}
<style>
    .jp-RenderedHTMLCommon p {
        font-size: 0.8rem;
        line-height: 1.6;
    }
    .jp-RenderedHTMLCommon li {
        font-size: .8rem;
        line-height: 1.6;
    }
    .jp-RenderedHTMLCommon h1 {
        margin: 0 0 1.25em;
        color: var(--md-default-fg-color--light);
        font-weight: 300;
        font-size: 2em;
        line-height: 1.3;
        letter-spacing: -0.01em;
    }
    .jp-RenderedHTMLCommon h2 {
        margin: 1.6em 0 .64em;
        font-weight: 300;
        font-size: 1.965em;
        line-height: 1.4;
        letter-spacing: -0.01em;
    }
    .jp-RenderedHTMLCommon h3 {
        margin: 1.6em 0 .8em;
        font-weight: 400;
        font-size: 1.57em;
        line-height: 1.5;
        letter-spacing: -0.01em;
    }
    .jp-RenderedHTMLCommon hr {
        border: none;
    }
</style>
{% endblock content %}

Pied de page#

Licence#

copyright: information de droit d'auteur qui s'affiche dans le pied de page pour toutes les pages du site

Exemple extrait du fichier mkdocs.yml de ce site : ...

Ce code YAML :génère le code HTML :

copyright: >
    Document partagé par <a href="https://github.com/ericECmorlaix" target="_blank">Eric MADEC</a>
    &copy; 2021 sous licence <a href="https://creativecommons.org/licenses/by-nc-sa/4.0/deed.fr" target="_blank">CC BY-NC-SA 4.0</a>
    <br> Illustrations par <a href="https://undraw.co/" target="_blank">UnDraw</a>

<div class="md-footer-copyright__highlight">
    Document partagé par <a href="https://github.com/ericECmorlaix" target="_blank">Eric MADEC</a> &copy; 2021 sous licence <a href="https://creativecommons.org/licenses/by-nc-sa/4.0/deed.fr" target="_blank">CC BY-NC-SA 4.0</a> <br> Illustrations par <a href="https://undraw.co/" target="_blank">UnDraw</a>
</div>

Liens sociaux#

social: permet d'afficher dans le pied de page pour toutes les pages du site des icônes support de liens sociaux.

Exemple extrait du fichier mkdocs.yml de ce site : ...

Ce code YAML :

extra:
social: 
    - icon: fontawesome/solid/paper-plane
    link: "mailto:eric.madec@ecmorlaix.fr?subject=ADN - Tutoriel documentation web&body=Votre question : ..."
    name: Pour toute question, suggestion ou commentaire, écrire à l'auteur
    - icon: fontawesome/brands/github
    link: https://github.com/ericECmorlaix/adn-Tutoriel_site_web
    name: dépôt github
    - icon: fontawesome/solid/university
    link: https://www.ecmorlaix.fr/nos-etablissements/lycee-notre-dame-du-mur/
    name: Lycée Notre Dame du Mur

Toujours en construction...#

Illustration par unDrawn de la construction d'un mur

GitHub Actions gère le déploiement du site par intégration continue (CI = Continuous Intégration). ↩

YAML pour la configuration#

Introduction#

Notions de YAML utiles#

Le fichier ci.yml#

Le fichier mkdocs.yml#

Configuration minimale#

Dépôt#

Métadonnées#

Stucture de navigation#

Thème#

Extensions MarkDown :#

Plugins#

Recherche#

MkDocs-Jupyter#

Pied de page#

Licence#

Liens sociaux#

Toujours en construction...#

Le fichier `ci.yml`#

Le fichier `mkdocs.yml`#