Prérequis
Pour pouvoir utiliser ces astuces, vous devez être administrateur d’une instance Discourse auto-hébergée ou disposer d’un plan hébergé par Discourse supérieur à Basic.
Introduction
Discourse prend en charge plusieurs méthodes pour formater et personnaliser le contenu d’un message. Vous pouvez consulter la liste ici :
Mais parfois, vous voudrez quelque chose de plus spécifique, par exemple un lien qui ressemble à un bouton.
C’est le 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 plonger directement dans un exemple pratique 
Discourse autorise tout attribut HTML commençant par data- dans le contenu d’un message.
Ce sont ces 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 une balise de type BBcode : [wrap], à laquelle 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 ayant 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 bloc
Dans votre message, sur une ligne vide, écrivez :
[wrap=pink]pink text[/wrap]
Cela créera un élément div ayant 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 → Modifier le CSS/HTML → CSS.
Placez le code CSS suivant à l’intérieur :
[data-wrap="pink"] {
background: pink;
}
Ensuite, cliquez sur le bouton Enregistrer.
Retournez à votre message et observez le résultat :
Oui, c’est déjà beau 
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 bloc.
Vous pouvez en savoir plus sur la différence entre les éléments HTML blocs et en ligne ici : HTML Block and Inline Elements.
Si vous voulez votre fond rose sur plusieurs lignes (toujours en tant que bloc), vos balises [wrap] doivent être seules sur leur ligne, sans aucun autre contenu ou texte :
[wrap=pink]
pink text
pink text
pink text
pink text
[/wrap]
Cela donnera ce résultat :
En tant qu’élément en ligne
Maintenant, ajoutons du texte avant la balise [wrap], ou après, ou les deux 
. Par exemple :
Here is some [wrap=pink]pink text[/wrap] and it's awesome ✨
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 en ligne.
Deuxième exemple : un lien avec l’apparence d’un bouton.
Jouer avec la balise [wrap] peut parfois entraîner des résultats indésirables pour diverses raisons, l’une d’elles étant qu’il peut s’agir d’un élément bloc ou en ligne selon le contexte.
Nous allons donc décrire deux méthodes différentes qui obtiennent le même résultat, mais vous pourrez choisir celle qui vous convient le mieux 
Un lien bouton en ligne avec [wrap]
La syntaxe pour créer un lien en utilisant Markdown est : [some text](https://some-link.etc).
Pour personnaliser le texte et le faire apparaître comme un bouton, nous insérerons le wrap à l’intérieur des crochets. Voici un exemple :
This [[wrap=button]nice link[/wrap]](https://discourse.org/) is a blue button 🐳 !
Nous ne commenterons pas ce que ce code génère. Vous savez que, parce que vous avez écrit [wrap=button], vous devrez cibler [data-wrap="button"] dans votre CSS.
Alors, allons-y, ajoutons un peu de CSS sophistiqué pour le rendre 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 sur le CSS sur Internet, donc si vous souhaitez effectuer des modifications plus spécifiques, vous devrez d’abord en apprendre davantage.
Le résultat 
:
Ça a l’air bien, non ?
Un lien bouton en ligne avec du contenu HTML standard
Puisque Discourse accepte le code HTML, nous pouvons décider de ne pas utiliser les balises [wrap] et d’utiliser du 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 :
This <span data-button>[link](https://discourse.org/)</span> is a green button 🐸 !
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 des contenus plus avancés. La limite est principalement votre connaissance du CSS (et du HTML dans une moindre mesure).
Je vais donner un seul exemple sans explication en personnalisant une liste dans laquelle chaque élément sera précédé d’un émoji de chat :
Texte :
[wrap=cat]
- Felix
- Garfield
- Nat's cat
[/wrap]
CSS :
[data-wrap="cat"] ul {
list-style: none;
li:before {
content: "🐈";
margin-right: 0.25em;
}
}
Résultat :
Utiliser les variables de couleurs de votre thème
Si vous autorisez les utilisateurs à utiliser des thèmes ou des couleurs différents, vos modifications peuvent ne pas bien paraître pour chacun d’entre eux, surtout s’ils ont le choix entre des schémas de couleurs clairs et sombres.
Une bonne pratique consiste à utiliser les variables de couleurs de Discourse au lieu de couleurs “codées en dur” telles que red, #FF0000 ou rgb(255,0,0).
Voici un exemple dans lequel la couleur de fond du bouton utilisera la couleur primaire de la palette actuelle, et le texte utilisera la couleur secondaire :
Texte :
This [[wrap=button]nice link[/wrap]](https://discourse.org/) is a button 🌈 !
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 le CSS est primordial. Vous trouverez de nombreux tutoriels sur Internet.
Le guide suivant de Discourse 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 couleurs de votre Discourse et l’aspect de chacune :
N’hésitez pas à suggérer toute modification pour ce guide !
Ce document est sous contrôle de version - suggérez des modifications sur github.
