Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

mdBook : Obliger les blocs de code à aller à la ligne automatiquement

Avertissement

Attention : cette astuce fonctionne sur tous les blocs de code SAUF les blocs de code ```rust,editable.

Et pourquoi donc ?

Lorsque nous activons l’option editable pour des codes Rust, c’est l’éditeur ACE (ACE Editor) qui prend le relais. Celui-ci bloque les retours à la ligne (wrap) dans son code JavaScript.

Il est toujours possible d’obtenir le même résultat, mais cela demande un patch logiciel (ou plus simplement patch). 1 Je ne traite pas les patchs dans ce livre.

Peut-être dans un futur projet qui pourrait s’appeler « Modifier mdBook pour l’améliorer avec des patchs »…
Peut-être si je reçois des demandes et surtout des soutiens…

Contexte

Par défaut, les blocs de codes sont considérés comme des lieux protégés dans la plupart des outils :

  • On ne modifie pas ni n’interprète les espaces ni les tabulations,
    • sauf exceptions : il en existe une dans mdBook dont je traite dans ce livre.
  • On respecte scrupuleusement les retours à la ligne.
  • etc.

Malheureusement, cela provoque parfois des blocs qu’il faut faire défiler horizontalement (horizontal scroll) pour voir l’ensemble du code, notamment sur les écrans de petites largeurs.

Ce comportement par défaut a une autre conséquence fâcheuse : les versions « imprimées » 2 ne permettent pas de voir tout le code sauf si le·la développeur·se du site a consciencieusement prévu ce qu’il faut dans une feuille de style pour « l’impression » 2. Chose de plus en plus rare, malheureusement.

Pour corriger ce comportement une bonne fois pour toutes pour l’ensemble de notre site web mdBook, nous pouvons (et devrions, sans tarder) intervenir des styles CSS de notre projet mdBook.

Ajout d’une feuille de styles personnalisée

Attention : Il ne faut pas modifier les feuilles de style de mdBook lui-même. Nous surchargeons à l’aide d’une feuille de styles personnalisée. C’est prévu dans le fonctionnement de l’outil.

Pour ajouter une feuille de styles personnalisée qui surcharge les styles de mdBook, nous ajoutons cette ligne dans book.toml :

output.html.additional-css = ["custom.css"]

Le dossier par défaut est le dossier racine du projet (nom-du-projet/).

Contenu de la feuille de style personnalisée

Nous intervenons sur le bloc .content main pre code et nous pouvons écrire une ou deux des lignes suivantes :

.content main pre code {
    white-space: pre-wrap;
    word-break: break-all;
}
  • white-space: pre-wrap; ajoute les retours à la ligne automatiques ;
  • word-break: break-all; autorise à couper n’importe quel mot n’importe où.

word-break: break-all; est agnostique.
word-break: break-all; permet de couper des éléments qui dépassent la largeur disponible sur l’écran (pour de petites résolutions, comme sur ordiphones par exemple).
Pour ces raisons, je le recommande VIVEMENT pour des blocs de codes.

Pour réviser CSS (inutile pour ce qui nous occupe ici)

La propriété CSS word-break: break-all; permet de forcer un retour à la ligne n’importe où, y compris au milieu d’un mot, dès que le texte dépasse de son conteneur.

Les autres valeurs possibles pour word-break

  • word-break: normal; (Valeur par défaut)
    Utilise les règles de césure par défaut de la langue. Les retours à la ligne se font uniquement au niveau des espaces ou des traits d’unions (ou tirets courts, que le navigateur ne sait pas distinguer). Les mots très longs (comme les URL) débordent du conteneur s’ils n’ont pas la place (ni de trait d’union).
  • word-break: keep-all; Interdit la césure des mots pour les langues CJC (Chinois, Japonais, Coréen). Pour les autres langues comme le français, elle se comporte exactement comme normal.

Les alternatives à word-break

Dans d’autres contextes, nous pouvons utiliser :

  • overflow-wrap: break-word; (anciennement word-wrap) et
  • hyphens: auto;.

  1. Je me suis servi du patch logiciel correspondant dans la page mdBook : Écrire des notes de bas de page plus complexes avec des retours à la ligne et d’autres éléments. 😉 ↩

  2. Nous veillons à enregistrer au format PDF et à ne pas imprimer physiquement, sauf impérieuse nécessité. Merci pour la planète, merci pour nous, merci pour les générations futures… ↩ ↩2