Un guide technique utile doit permettre de comprendre l’exemple, de le copier et de retrouver son rôle dans le projet. Prism améliore la lecture du code ; la structure de l’article et le contexte fourni autour de l’extrait restent essentiels.
Dans le design Phoenix communautaire, les articles classiques utilisent single-post.twig, tandis que les exemples de code restent dans le contenu WordPress.
Structurer le guide avant de colorer le code
Commencez par le problème traité et le résultat attendu. Présentez ensuite les prérequis, le fichier concerné, l’exemple et les contrôles à effectuer. Un lecteur doit savoir si le code remplace un fichier complet ou illustre seulement quelques lignes.
Évitez de multiplier les fragments qui dépendent de variables jamais définies. Quand un exemple est partiel, nommez explicitement ce qui doit déjà exister. Les archives téléchargeables servent à fournir les fichiers associés et un README.
Un bon titre de section décrit une action ou une décision : « Déclarer la feuille CSS » est plus utile que « Étape importante ».
Identifier le langage des blocs
Prism reconnaît un langage à partir d’une classe language-... sur le code ou un ancêtre. Le HTML de l’exemple doit être échappé pour être montré, plutôt qu’interprété par le navigateur.
<pre class="language-twig"><code>{% if title is not empty %}
<h2>{{ title|e }}</h2>
{% endif %}</code></pre>
Dans WordPress, utilisez un bloc Code et sa classe additionnelle lorsque votre éditeur le permet. Les guides livrés avec ce projet possèdent déjà les indications de langage nécessaires.
Pour un shortcode montré comme exemple, le rendu éditorial doit conserver le texte dans le bloc de code. Il ne doit pas transformer cette démonstration en un vrai bouton de téléchargement.
Déclarer Prism dans le design
Les fichiers CSS et JavaScript restent locaux et passent par assets/styles.json. Le build du projet inclut les langages employés par les guides : Twig, PHP, JavaScript, CSS, JSON, Bash et d’autres formats utiles aux exemples.
La barre d’outils et le bouton de copie sont intégrés. Leurs libellés sont configurés en français dans la zone de lecture. Aucune bibliothèque supplémentaire de copie n’est nécessaire.
Conservez la licence de Prism avec les fichiers livrés. Pour reproduire le build, les sources et la version sont documentées dans les assets du design.
Garder une lecture confortable
Les lignes longues doivent défiler dans le bloc de code sans provoquer un défilement horizontal de toute la page. Vérifiez ce comportement sur un petit téléphone.
Choisissez un contraste lisible pour les commentaires, les chaînes et les mots-clés. Un thème sombre peut convenir à l’identité du site, à condition que les couleurs de syntaxe restent compréhensibles.
Le bouton de copie doit être accessible au clavier et présenter un retour lorsque la copie réussit ou échoue. L’exemple doit rester sélectionnable manuellement si l’API de presse-papiers n’est pas disponible.
Ajouter des repères autour de l’article
La colonne latérale propose les liens utiles, les publications récentes et une façon de contacter l’équipe. Les lectures complémentaires en bas utilisent latest() pour rester reliées aux articles WordPress.
Dans le helper fourni, le tri par défaut est alphabétique. Le design applique donc un ajustement limité aux requêtes secondaires de l’article pour que « Publications récentes » corresponde bien à la date de publication. Le package Phoenix n’est pas modifié.
Le corps de l’article reste prioritaire sur mobile : les compléments passent après la lecture et ne réduisent pas sa largeur.
Vérifier l’exemple comme un lecteur
Copiez un extrait depuis la page publique, collez-le dans un fichier temporaire et contrôlez son contenu. Vérifiez les caractères <, >, les guillemets, les retours à la ligne et les commandes qui contiennent des variables.
Ajoutez une phrase après le code pour expliquer ce que le lecteur doit observer. Un extrait correctement coloré mais sans critère de réussite reste difficile à utiliser.
Consultez le guide de création d’un bloc pour un exercice complet et la recette de livraison pour les contrôles à partager avec l’équipe.
