Prérequis
Pour pouvoir utiliser ces astuces, vous devez être administrateur d’une instance Discourse auto-hébergée ou d’un plan hébergé par Discourse supérieur au Basic.
Introduction
Discourse prend en charge plusieurs méthodes pour formater et personnaliser le contenu d’un message. Vous trouverez la liste ici :
Mais parfois, vous aurez besoin de quelque chose de plus spécifique, par exemple un lien qui ressemble à un bouton.
C’est ce type de modification que nous allons apprendre ici.
La logique
Je vais brièvement expliquer la logique sous-jacente, mais vous pouvez passer à l’étape suivante et vous plonger dans un exemple pratique 
Discourse autorise n’importe quel attribut HTML commençant par data- dans le contenu d’un message.
Ce sont les attributs que nous ciblerons avec CSS pour personnaliser notre contenu.
Je les appellerai attributs data- dans ce tutoriel
Une façon de créer des éléments avec ces attributs est d’utiliser un tag similaire au BBcode : [wrap], auquel nous ajouterons une valeur de notre choix. Ici, nous choisissons “button” (cela pourrait être n’importe quoi d’autre, même le nom de votre chien 
) :
[wrap=button]some text[/wrap]
Cela générera un élément HTML avec l’attribut suivant : data-wrap="button".
Premier exemple : un fond rose
Commençons par un exemple pratique. Nous allons créer du texte avec un fond rose.
En tant qu’élément de type block
Dans votre message, sur une ligne vide, écrivez :
[wrap=pink]pink text[/wrap]
Cela créera un élément div avec l’attribut data-wrap="pink".
Ensuite, ajoutez le CSS suivant à votre thème.
Allez dans le panneau d’administration → Personnaliser → Thèmes → votre thème → Éditer CSS/HTML → CSS.
Collez le code CSS suivant à l’intérieur :
[data-wrap="pink"] {
background: pink;
}
Cliquez ensuite sur le bouton Enregistrer.
Retournez dans votre message et voyez le résultat :
Oui, c’est déjà magnifique 
Vous remarquerez que le fond couvre toute la largeur du message. Comme notre wrap est le seul élément sur sa ligne, il génère un élément de type block.
Vous pouvez en savoir plus sur la différence entre les éléments HTML block et inline ici : HTML Block and Inline Elements.
Si vous voulez votre fond rose sur plusieurs lignes (toujours en tant que block), vous devrez que vos balises [wrap] n’aient aucun autre contenu ou texte sur la même ligne :
[wrap=pink]
pink text
pink text
pink text
pink text
[/wrap]
Cela ressemblera à ceci :
En tant qu’élément inline
Maintenant, ajoutons du texte avant le [wrap], ou après, ou les deux 
. Par exemple :
Voici du [wrap=pink]texte rose[/wrap] et c'est génial ✨
Voici le résultat :
Si du texte ou d’autres éléments se trouvent sur la même ligne que l’une de vos balises [wrap], cela générera un élément de type inline.
Deuxième exemple : un lien avec l’apparence d’un bouton.
Manipuler la balise [wrap] peut parfois donner des résultats indésirables pour diverses raisons, notamment parce qu’elle peut être un élément block ou inline selon le contexte.
Nous allons donc décrire deux méthodes différentes qui aboutissent au même résultat, mais vous pourrez choisir celle qui vous convient le mieux 
Un lien-bouton inline avec [wrap]
La syntaxe pour créer un lien en markdown est : [quelque texte](https://quel-lien.etc).
Pour personnaliser le texte et le faire apparaître comme un bouton, nous allons insérer le wrap à l’intérieur des crochets. Voici un exemple :
Ce [[wrap=button]beau lien[/wrap]](https://discourse.org/) est un bouton bleu 🐳 !
Nous ne commenterons pas ce que ce code produit. Vous savez que, puisque vous avez écrit [wrap=button], vous devrez cibler [data-wrap="button"] dans votre CSS.
Alors, allons-y, ajoutons un peu de CSS élégant pour rendre cela joli ! 
[data-wrap="button"] {
display: inline-block;
padding: 0.5em 1em;
background: DodgerBlue;
color: White;
}
Nous ne détaillerons pas les règles CSS ici. Il existe de nombreuses ressources CSS sur Internet, donc si vous souhaitez effectuer des modifications plus spécifiques, vous devrez d’abord vous former à ce sujet.
Le résultat 
:
Ça a l’air bien, non ?
Un lien-bouton inline avec du contenu HTML standard
Puisque Discourse accepte le code HTML, nous pouvons décider de ne pas utiliser les balises [wrap] et utiliser HTML avec un attribut data-. Dans cet exemple, nous utiliserons la syntaxe Markdown standard pour le lien et l’entourerons de balises <span>.
Nous ne pouvons pas utiliser directement une balise de lien <a> car c’est une exception et elle n’autorise aucun attribut data-.
Écrivez :
Ce <span data-button>[lien](https://discourse.org/)</span> est un bouton vert 🐸 !
Cela générera un lien à l’intérieur d’une balise <span> ayant un attribut data-button, ce qui signifie que le CSS sera un peu plus compliqué. Nous devrons cibler à la fois data-button et le lien :
[data-button] {
display: inline-block;
padding: 0.5em 1em;
background: ForestGreen;
a {
color: White;
}
}
Et voici le résultat !
Pour aller plus loin
Une liste personnalisée utilisant [wrap]
Les balises [wrap] et les attributs data- peuvent être utilisés dans de nombreux contextes et vous pouvez personnaliser du contenu plus avancé. La limite est principalement votre connaissance de CSS (et dans une moindre mesure de HTML).
Je donnerai un seul exemple sans explication en personnalisant une liste où chaque élément sera précédé d’un emoji de chat :
Texte :
[wrap=cat]
- Felix
- Garfield
- Le chat de Nat
[/wrap]
CSS :
[data-wrap="cat"] ul {
list-style: none;
li:before {
content: "🐈";
margin-right: 0.25em;
}
}
Résultat :
Utiliser les variables de couleur de votre propre thème
Si vous autorisez les utilisateurs à utiliser différents thèmes ou couleurs, vos modifications peuvent ne pas bien s’afficher pour chacun, surtout s’ils ont le choix entre des schémas de couleurs clairs et sombres.
Une bonne pratique consiste à utiliser les variables de couleur de Discourse plutôt que des couleurs “en dur” telles que red, #FF0000 ou rgb(255,0,0).
Voici un exemple où la couleur de fond du bouton utilisera la couleur principale de la palette actuelle, et le texte utilisera la couleur secondaire :
Texte :
Ce [[wrap=button]beau lien[/wrap]](https://discourse.org/) est un bouton 🌈 !
CSS :
[data-wrap="button"] {
display: inline-block;
padding: 0.5em 1em;
background: var(--primary);
color: var(--secondary);
}
Voici à quoi cela ressemblera pour un utilisateur utilisant le schéma de couleurs Solarized Light :
Et s’ils utilisent le schéma de couleurs Solarized Dark :
Conclusion
Vous avez maintenant les bases pour créer des éléments personnalisés en utilisant l’élément [wrap] et les attributs data-.
Pour effectuer des personnalisations plus avancées, apprendre CSS est primordial. Vous trouverez de nombreux tutoriels sur Internet.
Le guide Discourse suivant peut également être utile : Making custom CSS changes on your site.
L’utilisation des outils de développement de votre navigateur Internet vous montrera également facilement la liste des variables de couleur de votre Discourse et à quoi chacune ressemble :
N’hésitez pas à suggérer toute modification pour ce guide !
Ce document est versionné - proposez des changements sur github.
