Support de <details> dans mdBook (CommonMark)

Lisez cette page jusqu’au bout : c’est… croustillant à souhait !

mdBook n’a pas prévu de développer les blocs <details> dans la version impression (print) de ses feuilles de style par défaut.

Ont-ils·elles raison de faire ainsi ? Est-ce une décision réfléchie ou un oubli ?

Toutes les balises HTML sont rendues en l’état

mdBook s’appuie sur CommonMark comme indiqué dans sa documentation officielle qui nous renvoie vers le guide Markdown https://www.markdownguide.org/ que je recommande à tous·tes ceux·celles qui souhaitent savoir comment se servir de Markdown dans sa variante CommonMark. ¹

CommonMark fait clairement référence à l’utilisation de code HTML « brut » ou « natif » (raw HTML) dans sa documentation officielle, au chapitre 6.6 : ²

« 6.6 HTML brut

Le texte entre < et > qui ressemble à une balise HTML est analysé comme une balise HTML brute et est rendu en HTML sans échappement.

Les noms de balises et d’attributs ne sont pas limités aux balises HTML actuelles, de sorte que des balises personnalisées (et même, par exemple, des balises DocBook) peuvent être utilisées. »

Clairement, le HTML est supporté et « véhiculé » au travers du parseur Markdown, et c’est une excellente chose.

Voir aussi : Le parseur Markdown utilisé par mdBook est pulldown-cmark

mdBook n’est pas responsable de prévoir tous les usages

mdBook n’est pas explicitement responsable de prévoir tous les usages que nous faisons du HTML dans nos projets mdBook.

Et ils·elles ont clairement choisi de NE PAS se fatiguer.

C’est la raison pour laquelle on ne trouve aucune référence CSS à cette balise HTML <details> dans les feuilles de styles de mdBook.

Ils pourraient le faire et se montrer brillant·e·s et attentionné·e·s

Cela dit, <details> est une balise bien connue du HTML et il n’est pas difficile de prévoir un comportement natif dans une feuille de styles à son sujet.

Ce serait une excellente idée, et une excellente chose, que de l’intégrer de base dans les feuilles de styles

• pour l’affichage à l’écran (screen) et
• pour l’affichage dans la version du livre mdBook pour impression (print).

En attendant, nous pouvons le faire nous-mêmes

En attendant, nous pouvons le faire nous-mêmes, comme beaucoup d’autres choses qui sont proposées dans ce livre mdBook.

Pris en flagrant délit

Je note au passage que nos ami·e·s de mdBook se sont tiré une balle dans le pied sans doute sans s’en apercevoir dans LEUR PROPRE DOCUMENTATION.

En effet, dans la page au sujet des préprocesseurs de la documentation officielle mdBook, plus précisément à la fin du chapitre de page mdBook « Se greffer sur mdBook » (« Hooking into mdBook ») ³, ils·elles utilisent une balise <details> pour n’afficher un bloc de code source que si nous cliquons pour le voir.

Devinez ce qui se produit lorsque l’on recherche ce morceau de code dans la version « imprimée » (PDF) de la documentation officielle de mdBook…

1. https://rust-lang.github.io/mdBook/format/markdown.html?highlight=CommonMark#markdown ↩

2. https://spec.commonmark.org/0.31.2/#raw-html ↩

3. https://rust-lang.github.io/mdBook/for_developers/preprocessors.html#hooking-into-mdbook ↩