Donc, vous êtes intéressé par la conception de votre propre thème pour Discourse ? Vous êtes au bon endroit 
Ce guide se concentrera davantage sur les aspects SCSS/CSS de la création de thèmes dans Discourse. Si vous maîtrisez également JS/EmberJs/Handlebars, vous pouvez aller plus loin en consultant ce guide.
Je vais vous décrire ma méthode personnelle de conception et de personnalisation de thèmes dans Discourse. Comme pour la plupart des choses, il existe de nombreuses façons de mettre en œuvre vos propres designs. J’aime beaucoup utiliser les outils d’inspection lors de la création de thèmes, et je vous montrerai à quelques reprises comment je procède dans ce post.
Préparation pour la personnalisation des thèmes
Veuillez lire le Guide du débutant pour l’utilisation des thèmes Discourse ainsi que la Structure des thèmes… avant de continuer. Une connaissance approfondie n’est pas nécessaire à ce stade, mais ces articles vous donneront un peu plus de familiarité avant de commencer.
Pour travailler au mieux avec la personnalisation des thèmes dans Discourse, je suggère de vous configurer avec les éléments suivants afin de vous offrir le processus de conception le plus rapide et le plus fluide possible. Ces étapes vous permettront de voir vos modifications à mesure que vous les apportez, sans avoir à « enregistrer » et rafraîchir depuis le panneau d’administration d’un site Discourse.
Il est tout à fait possible de suivre ce guide en utilisant la console d’administration (à condition d’avoir un accès au niveau administrateur à un forum Discourse.)
- Installez le Discourse Theme CLI et lisez ce sujet pour comprendre ce qu’il peut faire.
- Récupérez une clé API depuis https://discourse.theme-creator.io/
- Connectez-vous avec votre compte Meta
- Cliquez sur Mes Thèmes
- Cliquez sur Clé API
- Dans la fenêtre modale, cliquez sur Générer une clé API et copiez la clé générée pour vous (nous l’utiliserons dans un instant)
Exécution du Discourse Theme CLI
Une fois le Discourse Theme CLI installé et votre clé API prête, ouvrez votre éditeur de texte ou votre fenêtre de terminal préférée et changez votre répertoire de travail vers l’endroit où vous souhaitez que votre dossier de thème soit créé.
Une fois là-bas, exécutez la commande suivante discourse_theme new your_theme_name et remplissez les invites comme suit :
-
Comment souhaitez-vous appeler votre thème ? Choisissez le nom de votre thème
-
Souhaitez-vous commencer à surveiller ce thème ? Oui
-
Quelle est l’URL racine de votre site Discourse ?
https://discourse.theme-creator.io/ -
Souhaitez-vous que ce nom de site soit stocké dans… ? Oui
-
Quelle est votre clé API ? entrez la clé API que vous avez récupérée depuis theme creator
-
Souhaitez-vous que cette clé API soit stockée… ? Oui
-
Choisissez Créer et synchroniser avec un nouveau thème lorsque demandé
-
Choisissez Ne rien faire lorsque demandé au sujet des composants de thème enfant
Si tout s’est déroulé correctement, vous devriez maintenant pouvoir naviguer vers Mes Thèmes sur https://discourse.theme-creator.io/ et voir votre nouveau thème dans la liste des thèmes à gauche.
Pour voir ces changements en temps réel, cliquez sur le nom de votre thème, puis, en bas de la zone d’informations, cliquez sur Aperçu
Le Theme CLI surveille désormais également tous les changements dans le nouvellement créé répertoire, et enregistrera, ainsi que mettra à jour le thème sur theme-creator à chaque modification.
Premiers pas
Le Discourse Theme CLI a créé une structure de thème pour nous à l’intérieur du nom de dossier que nous avons spécifié dans la commande exécutée plus tôt. Beaucoup de fichiers sont générés que nous n’utiliserons pas, donc nous allons supprimer tout sauf les éléments suivants :
common/common.scss
desktop/desktop.scss
mobile/mobile.scss
about.json
À l’intérieur du répertoire, exécutez également rm -rf .git pour supprimer le suivi de version git, il ne sera pas nécessaire pour ce guide.
Votre répertoire de thème devrait maintenant ressembler à ceci :
Il est utile de noter que les styles que nous ajoutons à ces fichiers seront rendus dans leur cas d’utilisation respectif. Les styles dans common.scss seront appliqués à desktop + mobile, tandis que les styles dans desktop.scss ne seront appliqués qu’à la navigation sur desktop, et ceux dans mobile.scss ne s’appliqueront qu’aux vues mobiles.
Hello World (en couleur)
Discourse utilise SCSS pour son style, donc afin de mieux exploiter les styles, vous voudrez peut-être vous familiariser avec SASS, mais si ce n’est pas le cas, vous pourrez toujours suivre ce guide.
Bon, maintenant pour passer à ce que nous attendions tous… LA PERSONNALISATION !
Actuellement, notre about.json ne définit aucun color_schemes, donc collez le code suivant dans cette section puis enregistrez.
{
"name": "my theme",
"about_url": null,
"license_url": null,
"assets": {},
"color_schemes": {
"Default": {
"primary": "222222",
"secondary": "ffffff",
"tertiary": "0088cc",
"quaternary": "e45735",
"header_background": "ffffff",
"header_primary": "333333",
"highlight": "ffff4d",
"danger": "e45735",
"success": "009900",
"love": "fa6c8d"
}
}
}
Si votre navigateur est ouvert, vous n’auriez pas vu de changements prendre effet, car c’est le schéma de couleurs par défaut utilisé lorsqu’aucun schéma n’est présent.
Vue d’ensemble du thème
Afin d’avoir quelque chose à mettre en œuvre dans ce guide, je vais vous guider dans la création d’un thème simple basé sur cette palette de couleurs.
Changement de la couleur d’arrière-plan + Couleur du texte principal
Faisons quelque chose de très simple. Nous allons changer la valeur "Secondary" de notre schéma de couleurs actuel. Changeons-la en "secondary": "EEF4F7" (cela change la couleur d’arrière-plan). Changeons également la valeur "primary" en "203243".
Avec juste cette ligne, nous avons déjà changé l’apparence et le ressenti de notre forum. Beaucoup de personnalisations peuvent être faites en éditant simplement les couleurs du schéma de couleurs.
Utilisation du schéma de couleurs
Toutes les clés suivantes sont définies dans le fichier about.json sous le nom du schéma de couleurs correspondant. Ces descriptions sont une bonne référence pour vous aider à comprendre le but principal de chaque nom de variable :
| Couleur | Description |
|---|---|
| primary | La plupart des textes, icônes et bordures |
| secondary | La couleur d’arrière-plan principale, et la couleur du texte de certains boutons |
| tertiary | Liens, certains boutons, notifications et couleur d’accent |
| quaternary | Liens de navigation |
| header_background | Couleur d’arrière-plan de l’en-tête du site |
| header_primary | Textes et icônes dans l’en-tête du site |
| highlight | La couleur d’arrière-plan des éléments mis en surbrillance sur la page, tels que les publications et les sujets |
| danger | Couleur de surbrillance pour des actions comme la suppression de publications et de sujets |
| success | Utilisé pour indiquer qu’une action a réussi |
| love | La couleur du bouton de like |
Chacune de ces variables est disponible pour nous à l’intérieur de nos fichiers SCSS comme ceci.
body {
background-color: var(--primary);
}
D’autres versions de chaque couleur sont également créées pour nous permettre de les utiliser. Des choses comme var(--primary-medium), ou var(--primary-very-low) peuvent être utilisées pour obtenir différentes nuances de la même couleur.
Changeons les autres couleurs de notre schéma de couleurs “Default” pour correspondre à ceci :
"Default": {
"primary": "203243",
"secondary": "EEF4F7",
"tertiary": "416376",
"quaternary": "5E99B9",
"header_background": "FaFaFa",
"header_primary": "EEF4F7",
"highlight": "86BDDB",
"danger": "8F393E",
"success": "70DB82",
"love": "FC94CB"
}
Vous pouvez voir toutes les variables disponibles pour l’utilisation dans vos fichiers SCSS si vous cliquez sur le lien Guide de Style pendant l’aperçu de votre thème sur theme creator, puis cliquez sur Couleurs dans le menu à gauche.
Le Guide de Style est une section très utile à consulter lorsque vous créez un thème personnalisé. Chaque Atome vous montrera à quoi ressembleront certains éléments de Discourse avec vos styles appliqués.
Aller plus loin
Avec la section précédente derrière nous, je pense qu’il est temps d’aller un peu plus en profondeur sur ce qui peut être fait dans Discourse avec seulement SCSS. (Indice : BEAUCOUP !)
Style de l’en-tête
Vous remarquerez que nos modifications précédentes du schéma de couleurs ont laissé quelque chose à désirer avec notre en-tête. Les icônes sont à peine visibles !
L’en-tête Discourse comprend un conteneur (avec une couleur d’arrière-plan) pour contenir un logo de site, ainsi que les icônes de navigation à droite. Tout cela peut être personnalisé.
La classe cible pour personnaliser l’en-tête est .d-header.
Dans notre fichier common/common.scss, ajoutons ce qui suit :
.d-header {
box-shadow: none;
border-bottom: 1px solid var(--primary-low-mid);
height: 5em;
}
Cela supprimera l’ombre de boîte par défaut sur l’en-tête, lui donnera un peu plus de hauteur, ainsi que définir une bordure inférieure pour nous donner une certaine séparation.
Pour les icônes – À l’intérieur des crochets SCSS de .d-header, ajoutons ce code imbriqué.
.d-header {
// ...code précédent
.d-icon {
color: var(--primary-low-mid);
}
}
C’est bien, mais un œil averti remarquera que la hauteur d’en-tête accrue nous a donné moins d’espace entre lui-même et le reste des éléments du forum Discourse !
L’espacement entre la zone principale et l’en-tête est contrôlé par la cible #main-outlet. Augmentons cet espacement un peu en ajoutant ce qui suit en bas de votre fichier common/common.scss.
#main-outlet {
padding-top: 6.5em;
}
Conteneur de navigation
Le conteneur de navigation comprend les éléments suivants.
La zone la plus à gauche est les menus déroulants de filtre de catégorie/étiquette, suivis des liens de navigation, terminés par le bouton Nouveau Sujet.
Menu déroulant Catégorie / Étiquette
Faisons quelques modifications dans cette zone. Pour ce faire, ajoutez ce qui suit à votre fichier common.scss.
.navigation-container {
.select-kit.combo-box {
.select-kit-header {
border-radius: 0.9em;
background-color: var(--header_background);
}
}
}
Ici, nous ciblerons .select-kit-header pour leur donner chacun un rayon de bordure identique, ainsi qu’une couleur d’arrière-plan plus claire.
En cliquant sur l’un d’eux, un menu déroulant s’ouvre.
Actuellement, il a également des coins durs, donc ajoutons quelques styles pour arrondir ceux-ci ainsi que changer la couleur d’arrière-plan pour qu’elle soit la même que l’en-tête.
.navigation-container {
.select-kit.combo-box {
// ...code précédent
&.category-drop,
&.tag-drop {
.select-kit-body {
border-radius: 0.9em;
background-color: var(--header_background);
.select-kit-collection {
background-color: var(--header_background);
border-top-left-radius: 0px;
border-top-right-radius: 0px;
}
}
}
}
}
Cela donne le résultat suivant…
Si vous regardez de près, vous pouvez voir que nos modifications ont laissé une petite bordure visible en haut à droite de la zone de recherche.
Corrigeons cela en regardant dans l’inspecteur de notre navigateur. C’est toujours un outil super utile pour apprendre quelles classes/IDs nous devons cibler afin d’appliquer correctement les styles.
Avec le menu déroulant visible, faites un clic droit sur la zone de recherche et « Inspectez » l’élément dans votre navigateur.
Nous pouvons voir que cet input se trouve à l’intérieur d’un div avec une classe de select-kit-filter.
Si nous regardons les règles appliquées à ce sélecteur, nous pouvons voir qu’il a actuellement une bordure en haut et en bas, ainsi que du padding appliqué. Nous ne voulons changer que le style de la bordure du haut.
Ajoutez le code suivant imbriqué dans le scss .select-kit-body de plus tôt.
.select-kit.combo-box.category-drop,
.select-kit.combo-box.tag-drop {
.select-kit-body {
// ...code précédent
.select-kit-filter {
border-top: 0px;
}
}
}
Avec cela, notre code pour styliser le conteneur de navigation devrait ressembler à ceci.
.navigation-container {
// Menu déroulant Catégorie + Étiquette
.select-kit.combo-box {
.select-kit-header {
border-radius: 0.9em;
background-color: var(--header_background);
}
&.category-drop,
&.tag-drop {
.select-kit-body {
border-radius: 0.9em;
background-color: var(--header_background);
.select-kit-collection {
background-color: var(--header_background);
border-top-left-radius: 0px;
border-top-right-radius: 0px;
}
.select-kit-filter {
border-top: 0px;
}
}
}
}
}
Liens de navigation
Ajoutons quelques styles pour que ces liens de navigation ressemblent à ceci :
Utilisons à nouveau notre inspecteur pour découvrir ce que nous devrions cibler ici.
Nous pouvons voir que nos éléments de navigation sont à l’intérieur d’un UL avec une classe de "nav nav-pills ..."
Retournons dans notre fichier common.scss, sous la section précédente, mais toujours imbriqué à l’intérieur de navigation-container, ajoutons ce qui suit :
.nav-pills {
& > li a {
&.active {
color: var(--tertiary);
background-color: var(--secondary);
border-bottom: 4px solid var(--tertiary);
}
}
}
Ce changement ciblera uniquement nos liens avec une classe active qui sont des enfants de nav-pills. Ce changement devrait donner à notre lien actif l’apparence suivante :
C’est bien, mais j’aimerais que la bordure du bas ne s’étende que jusqu’au texte. Pour ce faire, au-dessus de la ligne &.active {, ajoutons ce qui suit, qui affectera tous les liens A à l’intérieur des balises <li> de navigation.
// ...autre code
.nav-pills {
& > li a {
padding: 0;
margin-right: 20px;
color: var(--tertiary-high);
border-bottom: 4px solid transparent;
&.active {
// ...plus de code
}
}
}
Maintenant, nous devons styliser l’effet « survol » pour qu’il soit le même que l’effet « actif ».
Sous notre &.active précédent, ajoutons
&:hover {
color: var(--tertiary);
background-color: var(--secondary);
border-bottom: 4px solid var(--primary);
}
Ainsi, tout notre code de navigation devrait maintenant ressembler à ceci :
// Nav Pills
.nav-pills {
& > li a {
padding: 0;
margin-right: 20px;
color: var(--tertiary-high);
border-bottom: 4px solid transparent;
&.active {
color: var(--tertiary);
background-color: var(--secondary);
border-bottom: 4px solid var(--tertiary);
}
&:hover {
color: var(--tertiary);
background-color: var(--secondary);
border-bottom: 4px solid var(--primary);
}
}
}
Boutons
Les boutons dans Discourse existent dans de nombreuses formes et tailles. Vous pouvez en voir une variété dans la section Boutons du Guide de Style.
J’aimerais changer la plupart des boutons de ce thème pour qu’ils soient arrondis avec une personnalisation spécifique. Cela changera le bouton + Nouveau Sujet, ainsi que d’autres boutons sur tout le site.
En bas de notre fichier common.scss, ajoutons ce qui suit :
.btn {
background-color: var(--header_background);
color: var(--primary);
border-radius: 1.2em;
border: 1px solid var(--primary-low-mid);
.d-icon {
color: var(--primary);
}
&:hover {
background-color: var(--quaternary-low);
color: var(--primary);
.d-icon {
color: var(--primary);
}
}
&.btn-default,
&.btn-primary {
padding: 10px 12px;
}
}
Cela donnera à nos boutons l’apparence suivante :
Maintenant que nos boutons sont stylisés, j’aimerais souligner quelque chose à propos du style des boutons et de l’importance de tester tous vos designs.
Allez cliquer sur un Sujet dans votre aperçu de site, puis appuyez sur le bouton répondre sur une réponse de sujet, ou depuis le bouton de réponse en bas du flux du sujet. Vous verrez que notre style de bouton a affecté certaines choses que nous n’avions peut-être pas prévues.
Je ne veux pas que ces boutons d’édition de texte soient affectés par mon style précédent. Cela nécessite un peu plus de SASS/CSS complexe, mais nous pouvons faire en sorte que notre code n’affecte pas ces boutons avec :not(). 
Ajoutons cette ligne de code, devant notre cible .btn actuelle. Cela dira à nos styles de ne s’appliquer qu’aux boutons qui ne sont pas des enfants de .d-editor-button-bar.
:not(.d-editor-button-bar) > .btn
Ok, ça a très bien fonctionné… mais attends ! Maintenant, il y a ce bizarre rebelle qui fait sa propre chose.
En l’inspectant dans le navigateur, je peux voir que ce bouton a une classe .select-kit-header car en cliquant sur cet engrenage, plus d’options s’afficheront.
Maintenant que nous savons que nous ne voulons PAS cibler ce bouton, ajoutons plus de fonctionnalités :not() à notre code.
:not(.d-editor-button-bar) >
.btn:not(.single-select-header)
Cela sélectionnera tous les boutons qui ne sont PAS des enfants de .d-editor-button-bar et qui n’ont pas la classe .single-select-header. Je sais que c’est un peu confus, mais à l’intérieur de Discourse, il y a beaucoup de pièces mobiles, donc parfois le style doit être très spécifique pour affecter correctement les éléments.
J’ai également remarqué que notre style actuel affecte de manière maladroite le bouton de fermeture de la modale. En cliquant sur n’importe quoi qui ouvre une modale, vous pourriez le voir, ou plus facilement, nous pouvons naviguer vers la section modale du Guide de Style.
Pour corriger cela, j’ajouterai une autre cible à notre code.
:not(.d-editor-button-bar) >
.btn:not(.single-select-header):not(.modal-close)
Continuer…
Je vois un autre bouton qui ne semble pas avoir été affecté par notre code. C’est le bouton Suivi situé tout en bas d’un flux de publication de sujet.
J’ajouterai la ligne suivante, après une virgule, à notre code .btn actuel.
:not(.d-editor-button-bar) >
.btn:not(.single-select-header):not(.modal-close),
.topic-notifications-button > .select-kit > .btn
Cela ciblera correctement le bouton qui apparaît dans cette section, et pour l’instant, nous avons terminé le style de la zone supérieure de notre forum.
Où aller à partir d’ici
Ce guide était destiné à effleurer la surface de la façon dont vous pouvez personnaliser votre propre thème pour Discourse. J’espère que vous avez maintenant plus d’insight sur la façon de cibler des zones de l’application pour vos propres personnalisations.
Rappelez-vous Beaucoup de choses peuvent être personnalisées en utilisant uniquement SCSS. Si vous souhaitez aller plus loin dans votre développement, je recommande de lire les articles liés en haut de ce post.
N’hésitez pas à poser toutes vos questions et je serai ravi d’essayer de vous aider, ou de vous orienter dans la bonne direction.
Ce document est sous contrôle de version - suggérez des modifications sur github.