Coloration syntaxique : highlight.js ou Shiki pour vos documentations

Une documentation technique réussie ne se limite pas à des explications claires : elle doit aussi présenter le code de façon lisible, attractive et cohérente avec l'identité visuelle du projet. La coloration syntaxique joue ici un rôle central, transformant un bloc de texte brut en un extrait immédiatement compréhensible. Les lecteurs parcourent souvent la documentation en quête d'exemples concrets, et la qualité du rendu influence directement leur perception du sérieux de votre projet.

Deux bibliothèques dominent aujourd'hui le paysage francophone du web : highlight.js, présente depuis plus d'une décennie, et Shiki, plus récente mais déjà adoptée par de nombreux frameworks modernes. Elles adoptent des philosophies différentes pour résoudre le même problème, et le choix entre les deux dépend moins de la taille de votre projet que de vos priorités en matière de fidélité visuelle, de performance et de simplicité d'intégration.

Pourquoi investir dans la mise en valeur du code

Les développeurs lisent du code bien plus vite qu'ils n'en écrivent. Une coloration adaptée réduit la charge cognitive en distinguant immédiatement les mots-clés, les chaînes de caractères, les commentaires et les variables. Dans une documentation destinée à un public varié, des débutants aux experts, ce repérage visuel facilite la mémorisation des conventions syntaxiques et accélère la prise en main d'une API ou d'un framework.

Au-delà du confort de lecture, la mise en valeur du code véhicule une image professionnelle. Les utilisateurs associent souvent la qualité du rendu à la qualité du logiciel sous-jacent. Une documentation négligée peut suffire à détourner un développeur d'un projet open source pourtant solide. À l'inverse, des blocs de code nets et harmonisés renforcent la confiance et invitent à l'expérimentation.

highlight.js, la solution éprouvée et légère

highlight.js fonctionne selon une approche classique : la bibliothèque identifie le langage à partir de motifs textuels ou d'une déclaration explicite, puis applique des classes CSS à des expressions régulières. Cette méthode, bien que moins précise que les analyseurs plus rigoureux, permet un chargement très rapide et un poids réduit. La bibliothèque reconnaît plus de 190 langages dès l'installation et propose une galerie de thèmes officiels ainsi que de nombreuses contributions communautaires.

L'un des grands avantages pratiques reste la simplicité de mise en œuvre. Une seule ligne suffit pour activer le surlignage via un CDN, et la configuration par défaut couvre la majorité des cas d'usage. Pour les projets qui publient rapidement leur documentation sans souhaiter investir du temps dans la chaîne de construction, highlight.js offre un excellent compromis entre fonctionnalité et facilité.

Shiki, la fidélité visuelle héritée de VS Code

Shiki adopte une approche très différente : elle exploite les grammaires TextMate utilisées par VS Code pour reproduire à l'identique le rendu de l'éditeur. Concrètement, chaque token de code est coloré en fonction des règles précises d'un thème donné, ce qui garantit une cohérence parfaite entre ce que vos développeurs voient dans leur éditeur et ce que vos utilisateurs découvrent dans la documentation.

Cette fidélité a un coût. Shiki repose sur un processus de tokenisation plus lourd, généralement exécuté au moment de la génération du site plutôt qu'à l'exécution dans le navigateur. Le bundle final reste léger pour l'utilisateur, mais le temps de build peut augmenter sensiblement sur les très gros volumes de pages. Pour les projets qui privilégient la précision chromatique et qui disposent déjà d'une étape de compilation, cet investissement se révèle souvent rentable.

Comparer les deux approches en pratique

Le critère le plus immédiat concerne la taille du bundle produit. highlight.js délivre un script d'environ une dizaine de kilo-octets gzip et fonctionne intégralement côté client, ce qui en fait une option idéale pour les sites statiques hébergés sans étape de build. Shiki, en revanche, demande un pré-rendu : le HTML généré contient déjà les balises colorées et la feuille de style du thème, ce qui élimine tout JavaScript à l'exécution.

La couverture des langages mérite également attention. highlight.js propose un catalogue étendu, mais certains langages rares ou récents peuvent nécessiter des correctifs manuels. Shiki, grâce à son ancrage dans l'écosystème VS Code, bénéficie automatiquement des grammaires TextMate nouvelles, avec un niveau de détail souvent supérieur pour des langages complexes comme Rust, TypeScript avancé ou les dialectes SQL modernes.

Enfin, le choix du thème influence directement la modularité. Les deux bibliothèques offrent des thèmes sombres et clairs, mais l'écosystème Shiki permet d'utiliser n'importe quel thème VS Code populaire sans adaptation. Si votre équipe a standardisé un thème d'éditeur interne, Shiki le reproduira sans effort dans la documentation.

Intégrer dans les générateurs de documentation modernes

Les frameworks de documentation comme Docusaurus, VitePress ou Astro s'intègrent nativement avec ces deux solutions. Docusaurus utilise d'ailleurs Shiki par défaut depuis ses versions récentes, ce qui en dit long sur la tendance actuelle du marché. La configuration se résume souvent à quelques lignes dans un fichier dédié, et le thème sélectionné s'applique uniformément à l'ensemble du site.

Pour les projets qui maintiennent une documentation riche et variée, ces outils offrent aussi des composants prêts à l'emploi pour les blocs de code, les onglets de langage et la copie en un clic. Une comparaison des bases NoSQL illustre bien la diversité des exemples que votre documentation peut accueillir, qu'il s'agisse de fragments JavaScript, de requêtes CQL ou de configurations YAML.

Si vous générez votre documentation avec un pipeline personnalisé, l'intégration reste accessible. Shiki expose des API Node.js simples qui s'intègrent dans n'importe quel script de build, et highlight.js propose des hooks pour les frameworks SSR comme Next.js ou Nuxt.

Faire le bon choix selon votre contexte

Pour un projet personnel, un blog technique ou une documentation légère, highlight.js reste le choix le plus pragmatique : zéro configuration, démarrage instantané, résultats propres. Pour un projet d'envergure avec une charte graphique exigeante, des centaines de pages et une forte cohérence visuelle avec l'éditeur de l'équipe, Shiki apporte une rigueur difficile à atteindre autrement.

La nature du contenu compte aussi. Si votre documentation inclut des exemples complexes, comme une messagerie temps réel avec Socket.IO, la précision des couleurs aide à distinguer les événements, les callbacks et les objets transmis. Dans ce type de contexte pédagogique, la fidélité de Shiki peut faire la différence entre un exemple clair et un exemple confus.

Bonnes pratiques pour un rendu impeccable

• Limitez le nombre de thèmes activés pour réduire le poids de la page, en proposant par exemple un mode clair et un mode sombre seulement.
• Déclarez toujours le langage dans la balise de code Markdown pour éviter toute détection automatique hasardeuse.
• Vérifiez le contraste des couleurs avec un outil d'accessibilité afin de respecter les recommandations WCAG pour les utilisateurs malvoyants.
• Mettez en place un test de régression visuelle qui détecte les changements lors des mises à jour de thème ou de version.
• Évitez les personnalisations trop créatives qui s'éloignent des conventions : un thème classique restera toujours plus lisible qu'un thème artistique.
• Documentez vos propres conventions de coloration dans un guide de contribution pour garder une cohérence d'équipe.
• Mesurez le temps de build après l'intégration de Shiki pour identifier les opportunités d'optimisation, comme la mise en cache des tokens.

Mettez en place la coloration syntaxique dès la première version de votre documentation et itérez au fil des retours utilisateurs. Testez les deux bibliothèques sur un échantillon représentatif, comparez le rendu avec vos yeux autant qu'avec des métriques, puis choisissez la solution qui sert le mieux la lisibilité de votre code. Vos lecteurs vous remercieront par un temps d'apprentissage réduit et une confiance accrue dans votre projet.