Syntaxe utilisée pour les pages de ce site

Pour ceux qui s’intéressent aux détails techniques de ce site de l’AP et qui voudraient créer ou modifier des articles, cette page explique la syntaxe Markdown utilisée ici. La syntaxe Markdown a été créée dans le but premier d’être aussi facile à écrire qu’à lire, sans devoir utiliser d’outils spéciaux pour rendre le code lisible.

La version actuelle de ce site utilise Hugo ainsi que quelques extensions pour convertir du texte contenant des balises Markdown en pages web statiques.

Il y a des centaines de sites web et de livres qui expliquent la syntaxe Markdown et ses différentes variantes. Cette page ne contient qu’un résumé de ce qui fonctionne bien sur ce site et qui ne pose pas de problèmes de compatibilité.

1. Syntaxe Markdown de base

1.1 Paragraphes

Les paragraphes sont constitués d’une ou plusieurs lignes de texte. Pour terminer un paragraphe, il suffit de laisser une ligne vide avant le paragraphe suivant.

Plusieurs lignes de texte sans ligne vide entre elles seront rassemblées dans un seul paragraphe. Pour forcer un retour à la ligne au milieu d’un paragraphe, il suffit de terminer une ligne par deux espaces puis un retour à la ligne.

1.2 Mise en forme simple

Markdown inclut quelques balises de mise en forme simple qui permettent de mettre du texte en évidence en gras ou en italique. Il n’y a pas de balises prédéfinies pour changer la taille, la forme ou la couleur des caractères. Ce n’est pas un oubli : cela permet de s’assurer que les pages de ce site pourront s’afficher correctement sur de nombreux types d’appareils (ordinateurs, téléphones, montres connectées, liseuses d’écran pour personnes mal-voyantes, etc.) et qu’il sera facile de les convertir en d’autres formats si nécessaire.

1.3 Listes

Pour obtenir une liste à puces, il suffit de commencer une ligne par une astérisque ou un tiret suivi d’un espace. Il doit y avoir une ligne vide avant et après la liste.

Une liste ordonnée est créée de la même manière, en utilisant des chiffres suivis d’un point au lieu des astérisques ou tirets :

1.4 Titres

Pour créer un titre, il suffit de commencer une ligne par un certain nombre de croisillons # suivis d’un espace puis du titre. Pour des raisons de compatibilité, il est fortement conseillé de laisser une ligne vide avant et après chaque titre.

Une autre option est d’écrire le titre suivi d’au moins trois === ou --- sur la ligne suivante :

Le titre de chaque page de ce site est déjà inclus comme titre de niveau 1. Il vaut donc mieux utiliser des titres de niveau 2 ou plus dans le texte de la plupart des pages. Les titres de niveau 1 n’apparaissent pas dans le sommaire (table des matières).

1.5 Liens vers d’autres pages

Les liens s’écrivent simplement en combinant des crochets et des parenthèses. Il suffit d’écrire le texte du lien entre crochets, suivi directement de la destination du lien (URL) entre parenthèses. Il est aussi possible d’ajouter un titre au lien, en l’ajoutant entre guillemets avant de fermer la parenthèse. Ce titre sera affiché lorsque l’utilisateur survole le lien avec la souris (mais pas sur téléphone ou autres appareils à écran tactile).

Si du texte contient quelque chose qui ressemble à une adresse web (URL) commençant par “https://” ou “www.”, alors ce sera converti automatiquement en lien sans qu’il soit nécessaire d’utiliser les crochets et les parenthèses. Il est aussi possible d’encadrer cette adresse avec les signes inférieur et supérieur à. Si en revanche vous souhaitez que l’adresse ne soit pas convertie en lien, alors il suffit de l’afficher comme code en l’entourant d’apostrophes inversées.

1.6 Images

La syntaxe permettant d’insérer des images est semblable à celle des liens. La différence est que la balise commence par un point d’exclamation. Le texte entre crochets est optionel et s’affichera si l’image ne peut pas être chargée ou si l’appareil utilisé pour lire ces pages ne permet pas l’affichage d’images.

Balise Markdown	Résultat


info TODO : Ajouter la documentation concernant les images SVG et le futur « shortcode » pour insérer ces images facilement.

1.7 Citations

Une citation consiste en un texte dont les lignes commencent par un chevron > suivi d’un espace :

1.8 Séparateur horizontal

Il est possible de tracer une ligne horizontale en incluant une ligne isolée contenant au moins trois tirets. Pour ne pas que ce soit confondu avec un titre, il faut laisser au moins une ligne blanche avant le séparateur.

2. Syntaxe Markdown ou HTML avancée

Les balises suivantes ne servent que dans des cas particuliers, comme par exemple pour les extraits de code affichés dans cette page. La plupart des auteurs n’auront pas besoin de ces balises.

2.1 Tableaux

Un tableau est constitué d’une ligne d’entête, d’une ligne de tirets indiquant qu’il s’agit d’un tableau, puis d’un certain nombre de lignes normales. Les colonnes sont séparées avec des |. Il est possible de préciser l’alignement des colonnes du tableau en utilisant des : dans la ligne de tirets.

Exemple :

| Texte aligné à gauche     | Texte centré |    Texte aligné à droite |
| :------------------------ |:------------:| -----:|
| Aligné à gauche  | Ce texte        |  Aligné à droite |
| Aligné à gauche  | est             |  Aligné à droite |
| Aligné à gauche  | centré          |  Aligné à droite |

Résultat :

Les bordures du tableau ne sont pas affichées. Pour les rendre visibles, il faut utiliser une extension définie ci-dessous. Par exemple, utiliser la classe “fancytable” donne le résultat suivant :

2.2 Notes de bas de page

Les notes de bas de page permettent d’ajouter des notes et références sans alourdir le texte du document. Ces notes apparaîtront comme des liens numérotés qui mèneront le lecteur en bas de page.

Pour créer une réference, il faut indiquer entre crochets un accent circonflexe suivi d’un nombre ou d’un mot (sans espace). Peu importe l’identifiant utilisé : les références seront toujours remplacées par des nombres en ordre croissant.

Le texte de la note de bas de page peut être défini n’importe où dans la page. Il faut utiliser une ligne commençant par les crochets contenant l´accent circonflexe suivi de l’identifiant, puis le symbole deux points immédiatement après le crochet fermant, et enfin le texte de la note.

Exemple :

Ceci est un texte avec une note de bas de page simple[^1] et une autre
plus longue[^notemulti] qui prend plusieurs lignes[^42].

[^1]: Exemple de note simple sur une seule ligne.

[^42]: Une deuxième note qui apparaîtra en troisième, car la
numérotation se fait en fonction de l'ordre des appels aux notes.

[^notemulti]: Exemple de note plus longue...

    Avec un deuxième paragraphe indenté par quatre espaces.

Résultat :

Ceci est un texte avec une note de bas de page simple¹ et une autre plus longue² qui prend plusieurs lignes³.

2.3 Blocs de code source

Selon la syntaxe de base de Markdown, un bloc de texte dont les lignes commencent par 4 espaces sera affiché comme du code source. Mais au lieu de cela, il est préférable d’utiliser une extension disponible sur ce site qui permet d’afficher comme code source tout bloc de texte précédé et suivi d’une ligne contenant trois accents graves ou apostrophes inversées ```. Cette syntaxe permet de préciser le langage de programmation utilisé et d’activer la coloration syntaxique.

Par exemple, le code suivant active la syntaxe “md” pour du code Markdown :

```md
## Ceci est un titre de niveau 2

Ceci est est un paragraphe de texte avec quelques mots en **gras** et
en *italique*. Il y a même un peu de code HTML : <span
class="green">test</span>.  La coloration syntaxique permet de repérer
plus facilement les balises spéciales dans un texte.
```

Ce code sera affiché comme ceci :

## Ceci est un titre de niveau 2

Ceci est est un paragraphe de texte avec quelques mots en **gras** et
en *italique*. Il y a même un peu de code HTML : <span
class="green">test</span>.  La coloration syntaxique permet de repérer
plus facilement les balises spéciales dans un texte.

Parmi les langages reconnus, les suivants sont utilisés pour des exemples présents dans cette page :

• text ou plain : texte simple sans coloration syntaxique.
• md : texte contenant des balises Markdown.
• html : code HTML.
• yaml : code YAML utilisé pour l’en-tête des pages.
• toml : code TOML utilisé pour la configuration de Hugo.

2.4 Listes de cases à cocher

Une liste (numérotée ou pas) peut être transformée en liste de cases à cocher. Il suffit d’ajouter [ ] ou [x] après le tiret ou le chiffre. Il est possible que certains navigateurs n’affichent pas correctement les cases à cocher ou permettent à l’utilisateur d’interagir avec ces cases alors que le but est de représenter une liste statique indiquant ce qui était coché ou pas au moment de la mise à jour de la page. Pour ces raisons, il vaut mieux ne pas trop utiliser ces balises.

2.5 Balises HTML

Ce site est configuré pour autoriser les balises HTML dans le code Markdown. Cela permet de faire des mises en forme particulières qui ne seraient pas possibles autrement, mais il faut les utiliser avec parcimonie. À l’avenir, les pages de ce site pourraient être converties avec un logiciel qui n’autorise plus les balises HTML ou qui ne les affiche plus de la même manière. De plus, utiliser des balises HTML peut poser des problèmes d’accessibilité pour les personnes utilisant une liseuse d’écran ou un logiciel de traduction automatique.

Les balises HTML simples telles que <sup> ou <sub> peuvent être utilisées sans grand risque. Mais dès qu’il s’agit de balises un peu plus complexes, il vaut mieux définir un “shortcode” Hugo qu’il sera plus facile de retrouver. Cela facilitera les éventuelles recherches et remplacements à l’avenir.

3. En-têtes de page (métadonnées)

Les pages Markdown utilisées par Hugo commencent généralement par quelques lignes d’en-tête qui décrivent le contenu et contrôlent la manière dont la page doit être générée. Ces lignes d’en-tête sont séparées du reste de la page par deux lignes de trois tirets « --- ».

Par exemple :

---
title: "Titre de la page"
date: 2020-12-31T23:59:59+02:00
draft: false
---

Cette déclaration attribue à la page le titre « Titre de la page », indique la date de première création de la page (cette date est ajoutée automatiquement par « make new-news » ou « hugo new ») et indique que ce n’est pas un brouillon.

3.1 « draft »

Lors de la création d’une nouvelle page avec « make new-news » ou « hugo new », le paramètre « draft: true » est ajouté automatiquement. Cela indique que la page est un brouillon qui n’est pas prêt à être publié officiellement. Cette page n’apparaîtra pas dans la liste automatique des pages récemment modifiées.

Lorsqu’une page est prête à être publiée officiellement, il faut changer ce paramètre en « draft: false ».

3.2 « authors »

Indique la liste des auteurs d’une page. C’est surtout utilisé pour les articles d’actualité (section /news/) et pour les PV de réunions (section /reunions/).

Par exemple :

---
title: "Titre de la page"
date: 2022-01-18T12:00:00+02:00
draft: false
authors:
  - Thierry de Marneffe, secrétaire
  - Raphaël Quinet, président
---

Lors de la création d’une nouvelle page avec « make new-news », le paramètre « authors » est ajouté avec comme nom initial « INCONNU_A_REMPLACER » pour ne pas qu’on oublie d’indiquer les noms de auteurs et l’article.

3.3 « toc »

Ajoute une table des matières si la page contient plus de 400 mots.

Par exemple, l’en-tête de cette page contient « toc: true » :

---
title: "Syntaxe utilisée pour les pages de ce site"
date: 2022-09-10T18:59:58+02:00
toc: true
draft: false
---

3.4 « robots »

Ajoute dans l’en-tête du fichier HTML généré : « <meta name="robots" content="(...)"> » pour contrôler la manière dont les robots de recherche et d’indexage traitent cette page. Par exemple :

---
title: "Titre de la page"
robots: "noindex, nofollow"
---

Cela va générer dans l’en-tête de la page :

  <meta name="robots" content="noindex, nofollow">

3.5 « hidden »

Ajoute dans l’en-tête du fichier HTML généré : « <meta name="robots" content="noindex"> »

Ajoute également une note au bas de la page générée, disant que la page est plus ou moins cachée car elle ne devrait pas être indexée, mais que toute personne qui dispose du lien ou qui le devine peut y accéder.

Le paramètre « hidden: true » est donc équivalent à « ‘robots: “noindex”’ » combiné avec l’ajout automatique d’un message en bas de page.

3.6 « original » et « command »

Ces deux paramètres sont ajoutés automatiquement par le script qui convertit un document vers le format Markdown. Le paramètre « original » est utilisé dans la section « /reunions/ » pour afficher au début de la page le nom original du fichier qui a été converti. Le paramètre « command » indique quelle commande a été utilisée pour effectuer la conversion.

4. Extensions (shortcodes) propres à ce site

Hugo permet de définir des extensions au format Markdown sous forme de « shortcodes » qui sont des balises spéciales, propres à ce site.

info TODO : Ajouter la documentation des nouvelles balises une fois qu’elles seront prêtes.

4.1 Balise « icon »

La balise {{< icon ... >}} permet d’inclure dans un texte certains symboles provenant de la collection Material Design Icons, tels que warning ou star. Voici quelques exemples :

4.2 Balise « classify »

La balise {{< classify ... >}} ... {{< /classify >}} permet d’entourer le texte spécifié par un élément (<div> par défaut) auquel est attribué une ou plusieurs classes CSS. Voici quelques exemples utilisant des classes définies pour ce site de l’AP :

info TODO : Certaines de ces mises en forme pourraient être remplacées par la nouvelle syntaxe des « blockquote render hooks » avec « > » suivi de « [!NOTE] », « [!TIP] », etc. mais cela demande une version de Hugo supérieure ou égale à v0.134.0.

info TODO : Il vaudrait mieux remplacer les styles « fancytable », « compacttable » et « layouttable » par un shortcode spécifique tel que {{< ap-table ... >}}

Classify note

{{< classify note >}}
Les éléments de type "note" apparaissent dans un cadre bleu foncé aux coins arrondis.
{{< /classify >}}

Classify info

{{< classify info >}}
Les éléments de type "info" apparaissent dans un cadre vert aux coins arrondis.
{{< /classify >}}

Classify warning

{{< classify warning >}}
Les éléments de type "warning" apparaissent dans un cadre orange aux coins arrondis.
{{< /classify >}}

Classify left

{{< classify left >}}
Ce texte flotte à gauche.  
Bla bla bla...
{{< /classify >}}
La suite du texte remplit  
l'espace restant à droite.

Classify right

{{< classify right >}}
Ce texte flotte à droite.  
Bla bla bla...
{{< /classify >}}
La suite du texte remplit  
l'espace restant à gauche.

Classify clear

Utiliser “clear” permet de s’assurer qu’il n’y a plus d’élément flottants ni à gauche ni à droite. Il est aussi possible de laisser vide l’élément “clear” : les éléments suivants seront placés après les éléments flottants.

{{< classify left >}}
Ce texte flotte à gauche.  
Bla bla bla...
{{< /classify >}}
{{< classify clear >}}
Avec "clear", la suite du  
texte continue plus bas.
{{< /classify >}}

Classify narrow

Le style “narrow” s’assure qu’un élément ne pourra pas dépasser un quart de la largeur de la page. En le combinant avec “left” ou “right” pour l’alignement et un des styles “note”, “info” ou “warning”, on peut obtenir une boîte pour placer des commentaires sur le côté de la page.

{{< classify "narrow left info" >}}
Ce texte flotte à gauche. Il ne pourra pas dépasser un quart de la
largeur de la page.
{{< /classify >}}
{{< classify "narrow right note" >}}
Ce texte flotte à droite. Il ne pourra pas dépasser un quart de la
largeur de la page.
{{< /classify >}}
La suite du texte remplit l'espace restant.

Classify fancytable

Le style “fancytable” permet d’ajouter des bords verts à une table, d’augmenter les espaces autour du texte, et de mettre en évidence la rangée que l’on survole à la souris.

{{< classify "fancytable clear" >}}
| titre 1 | titre 2 |
|---------|---------|
| machin  | truc    |
| bidule  |         |
{{< /classify >}}

Classify compacttable

Le style “compacttable” est similaire à “fancytable” mais réduit les espaces autant que possible.

{{< classify "compacttable clear" >}}
| titre 1 | titre 2 |
|---------|---------|
| machin  | truc    |
| bidule  |         |
{{< /classify >}}

Classify layouttable

Le style “layouttable” est une table sans bordures très semblable à la table de base mais avec un petit espace à droite de chaque colonne afin que les colonnes ne soient pas collées les unes aux autres. Les titres sont alignés à gauche au lieu d’être centrés.

{{< classify "layouttable clear" >}}
| titre 1 | titre 2 |
|---------|---------|
| machin  | truc    |
| bidule  |         |
{{< /classify >}}

Si on n’utilise que la table de base sans le style “layouttable”, les colonnes sont trop proches les unes des autres :