Comment rédiger un article Jekyll

Guide complet pour rédiger et mettre en forme un article Jekyll avec le thème Chirpy : métadonnées, images, code, médias et fonctionnalités intégrées.

Posté 18/02/2024 Mis à jour 12/10/2026

Par alxblzd

11 min lire

Comment rédiger un article Jekyll

Ce guide explique comment rédiger un article avec le thème Chirpy. Même si vous avez déjà utilisé Jekyll, un survol vaut la peine, car certaines fonctionnalités nécessitent des variables précises.

Nommage et chemin

À la racine, créez un fichier AAAA-MM-JJ-TITRE.EXTENSION dans _posts. EXTENSION doit être md ou markdown. Pour gagner du temps, utilisez Jekyll-Compose.

Polices

Image de couverture : Coolvetica RG, taille 36 dans paint.net. Exportez en WebP à 1200x630.

Conversion des médias

Convertissez les fichiers PNG en WebP pour ce site :

  
sudo apt install webp 
sudo pacman -Syu webp

Pour convertir une image en WebP, -q définit la qualité de sortie et -o le fichier de sortie.

cwebp -q 85 myimg.png -o myimg.webp

Script personnalisé pour convertir tous les fichiers .png en .webp dans un dossier :

  
#!/bin/bash
usage() {
    echo "Usage: $0 [-q quality]"
    echo "  -q quality : Set the quality for the webp conversion (default is 85)"
    exit 1
}

quality=85

while getopts "q:" opt; do
    case ${opt} in
        q )
            quality=$OPTARG
            ;;
        \? )
            usage
            ;;
    esac
done

current_dir=$(basename "$PWD")

new_dir="${current_dir}_conv"

mkdir -p "$new_dir"

for file in *.png; do
    if [ -f "$file" ]; then
        new_file="${new_dir}/$(basename "${file%.png}.webp")"
        cwebp -q "$quality" "$file" -o "$new_file"
        echo "Converted $file to $new_file with quality $quality"
    fi
done

for file in *.jpg *.jpeg; do
    if [ -f "$file" ]; then
        new_file="${new_dir}/$(basename "${file%.*}.webp")"
        cwebp -q "$quality" "$file" -o "$new_file"
        echo "Converted $file to $new_file with quality $quality"
    fi
done

echo "Conversion complete!"
exit 0

Métadonnées (Front Matter)

En résumé, vous devez renseigner les métadonnées de tête (Front Matter) comme ci-dessous, au début de l’article :

  
---
title: TITLE
date: YYYY-MM-DD HH:MM:SS +/-TTTT
categories: [TOP_CATEGORIE, SUB_CATEGORIE]
tags: [TAG]     # TAG names should always be lowercase
---

Par défaut, la mise en page (layout) des articles est définie sur post : il n’est donc pas nécessaire d’ajouter la variable layout dans le bloc Front Matter.

Fuseau horaire de la date

Pour enregistrer correctement la date de publication, définissez timezone dans _config.yml et indiquez le fuseau horaire de l’article dans date du Front Matter. Format : +/-TTTT, par exemple +0800.

Catégories et tags

categories peut contenir jusqu’à deux éléments ; tags peut en contenir autant que vous le souhaitez. Par exemple :

  
---
categories: [Animal, Insect]
tags: [bee]
---

Informations sur l’auteur

Les informations sur l’auteur proviennent généralement de social.name et de la première entrée de social.links. Pour les remplacer, ajoutez les données de l’auteur dans _data/authors.yml (créez ce fichier s’il n’existe pas) :

  
<author_id>:
  name: <full name>
  twitter: <twitter_of_author>
  url: <homepage_of_author>

Utilisez ensuite author pour une entrée unique ou authors pour plusieurs entrées :

  
---
author: <author_id>                     # for single entry
# or
authors: [<author1_id>, <author2_id>]   # for multiple entries
---

La clé author peut également désigner plusieurs entrées.

La lecture des informations de l’auteur dans _data/authors.yml ajoute la balise meta twitter:creator, ce qui enrichit les Twitter Cards et contribue au référencement.

Description de l’article

Par défaut, les premiers mots de l’article apparaissent sur la page d’accueil, dans À lire ensuite et dans le flux RSS. Pour remplacer la description générée automatiquement, définissez description dans le Front Matter :

  
---
description: Short summary of the post.
---

Cette description apparaît également sous le titre de l’article.

Table des matières

Par défaut, la table des matières (TOC) apparaît à droite. Pour la désactiver partout, définissez toc sur false dans _config.yml. Pour la désactiver dans un seul article, ajoutez ceci à son Front Matter :

  
---
toc: false
---

Commentaires

Définissez le paramètre global des commentaires avec comments.active dans _config.yml. Une fois le système choisi, les commentaires sont activés pour tous les articles.

Pour désactiver les commentaires d’un article, ajoutez ceci à son Front Matter :

  
---
comments: false
---

Mathématiques

Nous utilisons MathJax pour les formules mathématiques. Il est désactivé par défaut pour des raisons de performances, mais vous pouvez l’activer ainsi :

  
---
math: true
---

Après avoir activé les mathématiques, utilisez les formes suivantes :

Formules en bloc : $$ math $$, avec des lignes vides obligatoires avant et après $$
- Numérotation des équations : $$\begin{equation} math \end{equation}$$
- Références numérotées : \label{eq:label_name} dans le bloc et \eqref{eq:label_name} en ligne
Formules en ligne (dans les lignes) : $$ math $$ sans ligne vide avant ou après
Formules en ligne (dans les listes) : \$$ math $$

  
<!-- Block math, keep all blank lines -->

$$
LaTeX_math_expression
$$

<!-- Equation numbering, keep all blank lines  -->

$$
\begin{equation}
  LaTeX_math_expression
  \label{eq:label_name}
\end{equation}
$$

Can be referenced as \eqref{eq:label_name}.

<!-- Inline math in lines, NO blank lines -->

"Lorem ipsum dolor sit amet, $$ LaTeX_math_expression $$ consectetur adipiscing elit."

<!-- Inline math in lists, escape the first `$` -->

1. \$$ LaTeX_math_expression $$
2. \$$ LaTeX_math_expression $$
3. \$$ LaTeX_math_expression $$

Depuis la version v7.0.0, les options MathJax se trouvent dans assets/js/data/mathjax.js. Modifiez-les au besoin, par exemple pour ajouter des extensions.
Si vous utilisez chirpy-starter, copiez ce fichier depuis le répertoire d’installation du gem (voir bundle info --path jekyll-theme-chirpy) dans votre dépôt.

Mermaid

Mermaid est pratique pour créer des diagrammes. Pour l’activer dans un article, ajoutez ceci au bloc YAML :

  
---
mermaid: true
---

Utilisez ensuite Mermaid comme n’importe quel bloc délimité : encadrez le code du graphique avec ```mermaid et ```.

Images

Légende

Ajoutez une ligne en italique après une image pour afficher une légende en dessous :

  
![img-description](/path/to/image)
_Image Caption_

Taille

Indiquez la largeur et la hauteur de chaque image pour éviter les décalages de mise en page pendant son chargement :

  
![Desktop View](/assets/img/sample/mockup.png){: width="700" height="400" }

Pour un SVG, vous devez au moins spécifier sa largeur, sinon il ne sera pas affiché.

Depuis Chirpy v5.0.0, height et width acceptent des abréviations (height → h, width → w). Le résultat est identique :

  
![Desktop View](/assets/img/sample/mockup.png){: w="700" h="400" }

Position

Les images sont centrées par défaut. Pour changer leur position, utilisez normal, left ou right.

Une fois la position définie, il ne faut pas ajouter de légende à l’image.

Position normale
Dans cet exemple, l’image est alignée à gauche :
1 ![Desktop View](/assets/img/sample/mockup.png){: .normal }

Flottement à gauche

  
![Desktop View](/assets/img/sample/mockup.png){: .left }

Flottement à droite

  
![Desktop View](/assets/img/sample/mockup.png){: .right }

Mode clair/sombre

Vous pouvez remplacer les images selon le mode clair ou sombre. Fournissez deux images et attribuez-leur la classe dark ou light :

  
![Light mode only](/path/to/light-mode.png){: .light }
![Dark mode only](/path/to/dark-mode.png){: .dark }

Ombre

L’effet d’ombre convient bien aux captures de fenêtres :

  
![Desktop View](/assets/img/sample/mockup.png){: .shadow }

URL CDN

Si vos médias sont hébergés sur un CDN, définissez cdn dans _config.yml pour éviter de répéter l’URL :

  
cdn: https://cdn.com

Une fois défini, le préfixe CDN est ajouté à tous les chemins de médias commençant par / (avatars, images, audio et vidéo).

Par exemple, pour une image :

  
![The flower](/path/to/flower.png)

Le résultat du traitement ajoutera automatiquement le préfixe https://cdn.com avant le chemin de l’image :

  
<img src="https://cdn.com/path/to/flower.png" alt="The flower" />

Sous-chemin des médias

Pour les articles contenant beaucoup d’images, évitez de répéter les chemins en définissant media_subpath dans le bloc YAML :

  
---
media_subpath: /img/path/
---

Référencez ensuite les images par leur nom de fichier uniquement :

  
![The flower](flower.png)

Le résultat sera :

  
<img src="/img/path/flower.png" alt="The flower" />

Image d’aperçu

Pour l’image au début de l’article, utilisez une image de 1200 x 630. Si son ratio n’est pas de 1.91 : 1, elle sera redimensionnée et recadrée.

Dans ce cas, définissez les attributs de l’image :

  
---
image:
  path: /path/to/image
  alt: image alternative text
---

media_subpath s’applique aussi à l’image d’aperçu. S’il est défini, path doit uniquement contenir le nom du fichier.

Pour une utilisation simple, vous pouvez aussi définir directement le chemin avec image.

  
---
image: /path/to/image
---

LQIP

Pour les images d’aperçu :

  
---
image:
  lqip: /path/to/lqip-file # or base64 URI
---

Vous pouvez voir le LQIP sur l’image d’aperçu de cet article.

Pour les images ordinaires :

  
![Image description](/path/to/image){: lqip="/path/to/lqip-file" }

Articles épinglés

Vous pouvez épingler un ou plusieurs articles en haut de la page d’accueil ; les articles épinglés sont triés par date de publication décroissante. Activez cette fonction ainsi :

  
---
pin: true
---

Encadrés

Les types d’encadrés comprennent tip, info, warning et danger. Ajoutez la classe prompt-{type} à une citation. Par exemple :

> Example line for prompt.
{: .prompt-info }

Syntaxe

Code en ligne

`inline code part`

Mise en évidence des chemins de fichiers

`/path/to/a/file.extend`{: .filepath}

Bloc de code

Les délimiteurs Markdown ``` créent un bloc de code :

  
```
This is a plaintext code snippet.
```

Spécifier le langage

Avec ```{language}, vous obtiendrez un bloc de code avec coloration syntaxique :

  
```yaml
key: value
```

La balise Jekyll {% highlight %} n’est pas compatible avec ce thème.

Numérotation des lignes

Par défaut, tous les langages, sauf plaintext, console et terminal, affichent des numéros de ligne. Pour les masquer dans un bloc de code, ajoutez-lui la classe nolineno :

  
```shell
echo 'No more line numbers!'
```
{: .nolineno }

Spécifier le nom de fichier

Vous avez peut-être remarqué que le langage du code apparaît en haut du bloc. Pour le remplacer par le nom du fichier, ajoutez l’attribut file :

  
```shell
# content
```
{: file="path/to/file" }

Code Liquid

Pour afficher un extrait Liquid, entourez le code Liquid avec {% raw %} et {% endraw %} :

  
{% raw %}
```liquid
{% if product.title contains 'Pack' %}
  This product's title contains the word Pack.
{% endif %}
```
{% endraw %}

Vous pouvez aussi ajouter render_with_liquid: false au bloc YAML de l’article (nécessite Jekyll 4.0 ou une version ultérieure).

Vidéos

Vous pouvez intégrer une vidéo avec la syntaxe suivante :

  
{% include embed/{Platform}.html id='{ID}' %}

Platform est le nom de la plateforme en minuscules et ID l’identifiant de la vidéo.

Le tableau ci-dessous indique comment trouver ces valeurs sur les plateformes compatibles :

URL de la vidéo	Plateforme	ID
https://www.youtube.com/watch?v=H-B46URT4mg	`youtube`	`H-B46URT4mg`
https://www.twitch.tv/videos/1634779211	`twitch`	`1634779211`
https://www.bilibili.com/video/BV1Q44y1B7Wf	`bilibili`	`BV1Q44y1B7Wf`

Fichier vidéo

Pour intégrer directement un fichier vidéo, utilisez :

  
{% include embed/video.html src='{URL}' %}

URL désigne un fichier vidéo, par exemple /assets/img/sample/video.mp4.

Vous pouvez également transmettre des attributs :

poster='/path/to/poster.png' - image d’affiche de la vidéo, affichée pendant son téléchargement
title='Text' - titre de la vidéo, affiché dessous comme pour les images
autoplay=true - la lecture de la vidéo commence automatiquement dès que possible
loop=true - revient automatiquement au début une fois la lecture terminée
muted=true - le son est initialement coupé
types - extensions de formats vidéo supplémentaires, séparées par |. Vérifiez que ces fichiers se trouvent dans le même dossier que le fichier vidéo principal.

Exemple avec toutes les options :

  
{%
  include embed/video.html
  src='/path/to/video/video.mp4'
  types='ogg|mov'
  poster='poster.png'
  title='Demo video'
  autoplay=true
  loop=true
  muted=true
%}

Évitez d’héberger des fichiers vidéo dans assets, car le PWA ne les mettra pas en cache et cela peut causer des problèmes. Utilisez plutôt un CDN ou un dossier exclu du PWA (voir pwa.deny_paths dans _config.yml).

Audios

Fichier audio

Pour intégrer directement un fichier audio, utilisez :

  
{% include embed/audio.html src='{URL}' %}

URL désigne un fichier audio, par exemple /assets/img/sample/audio.mp3.