Vous souhaitez donc créer votre propre thème pour Discourse ? Vous êtes au bon endroit 
Ce guide se concentrera davantage sur les aspects SCSS/CSS du travail avec les thèmes dans Discourse. Si vous maîtrisez également JS/EmberJs/Handlebars, vous pouvez aller encore plus loin en consultant ce guide.
Je vais vous décrire ma méthode personnelle pour concevoir et thématiser 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 à plusieurs reprises comment je procède dans cet article.
Configuration pour la thématique
Veuillez lire le Guide pour débutants sur 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 thématique dans Discourse, je vous suggère de vous configurer avec les éléments suivants pour vous offrir un processus de conception le plus rapide et le plus fluide possible. Ces étapes vous permettront de voir vos modifications au fur et à mesure que vous les effectuez, sans avoir à ‘sauvegarder’ et rafraîchir depuis un panneau d’administration de site Discourse.
Il est tout à fait possible de suivre ce guide en utilisant la console d’administration (à condition que vous ayez un accès de niveau administrateur à un forum Discourse.)
- Installez 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 qui s’ouvre, cliquez sur Générer une clé API et copiez la clé générée pour vous (nous l’utiliserons un peu plus tard)
Exécution de Discourse Theme CLI
Avec Discourse Theme CLI installé et votre clé API prête, ouvrez votre éditeur de texte ou votre fenêtre de terminal préféré et changez votre répertoire de travail vers l’endroit où vous souhaitez configurer votre dossier de thème.
Une fois là-bas, exécutez la commande suivante discourse_theme new your_theme_name et remplissez les invites comme suit :
-
Comment souhaitez-vous nommer 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 enregistré dans… ? Oui
-
Quelle est votre clé API ? saisissez la clé API que vous avez récupérée depuis le créateur de thèmes
-
Souhaitez-vous que cette clé API soit enregistrée… ? Oui
-
Choisissez Créer et synchroniser avec un nouveau thème lorsque vous y êtes invité
-
Choisissez Ne rien faire lorsque vous êtes invité à propos des composants de thème enfant
Si tout fonctionne 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 modifications 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 CLI de thème surveille également toute modification dans le nouveau répertoire créé, et sauvegardera, ainsi que mettra à jour le thème sur theme-creator à chaque modification.
Premiers pas
Le CLI de thème Discourse a créé une structure de thème pour nous à l’intérieur du nom de dossier que nous avons spécifié dans la commande que nous avons exécutée plus tôt. De nombreux fichiers sont générés que nous n’utiliserons pas, nous allons donc supprimer tout sauf ce qui suit :
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 des versions git, ce qui ne sera pas nécessaire pour ce guide.
Votre répertoire de thème devrait maintenant ressembler à ceci :
Il est important 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 aux versions bureau et mobile, tandis que les styles dans desktop.scss ne seront appliqués qu’à la navigation sur bureau, et ceux dans mobile.scss ne s’appliqueront qu’aux vues mobiles.
Hello World (en couleur)
Discourse utilise SCSS pour son style, donc pour mieux exploiter les styles, vous voudrez peut-être vous familiariser avec SASS, mais sinon, vous pourrez toujours suivre ce guide.
Ok, maintenant passons à ce que nous attendons tous… LA THÉMATIQUE !
Pour le moment, notre about.json ne contient actuellement aucun schéma de couleurs défini, alors collez le code suivant dans cette section puis sauvegardez.
{
"name": "mon thème",
"about_url": null,
"license_url": null,
"assets": {},
"color_schemes": {
"Défaut": {
"primary": "222222",
"secondary": "ffffff",
"tertiary": "0088cc",
"quaternary": "e45735",
"header_background": "ffffff",
"header_primary": "333333",
"highlight": "ffff4d",
"danger": "e45735",
"success": "009900",
"love": "fa6c8d"
}
}
}
Si vous avez votre navigateur ouvert, vous n’auriez pas vu de changements prendre effet, car il s’agit du schéma de couleurs par défaut utilisé lorsqu’aucun schéma n’est présent.
Aperçu du thème
Pour avoir quelque chose à mettre en œuvre réellement dans ce guide, je vais vous accompagner 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 modifier 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 de notre forum. Beaucoup de personnalisation peut être faite simplement en modifiant les couleurs dans le 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 l’objectif 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’accentuation |
| quaternary | Liens de navigation |
| header_background | Couleur d’arrière-plan de l’en-tête du site |
| header_primary | Texte et icônes dans l’en-tête du site |
| highlight | La couleur d’arrière-plan des éléments mis en évidence sur la page, tels que les publications et les sujets |
| danger | Couleur de mise en évidence pour les actions comme la suppression de publications et de sujets |
| success | Utilisé pour indiquer qu’une action a réussi |
| love | La couleur du bouton J’aime |
Chacune de ces variables est disponible pour être utilisée dans nos fichiers SCSS comme suit.
body {
background-color: var(--primary);
}
D’autres versions de chaque couleur sont également créées pour notre utilisation. Des choses comme var(--primary-medium) ou var(--primary-very-low) peuvent être utilisées pour obtenir différents tons de la même couleur.
Modifions les autres couleurs de notre schéma de couleurs “Défaut” pour qu’elles correspondent à ceci :
"Défaut": {
"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 à utiliser dans vos fichiers SCSS en cliquant sur le lien Guide de style lors de l’aperçu de votre thème sur le créateur de thèmes, puis en cliquant sur Couleurs dans le menu de 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 loin dans ce qui peut être fait dans Discourse avec seulement SCSS. (Indice : BEAUCOUP !)
Styliser 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 de 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. Tous ces éléments peuvent être personnalisés.
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 portée par défaut sur l’en-tête, lui donnera un peu plus de hauteur et définira une bordure inférieure pour nous donner une certaine séparation.
Pour les icônes – À l’intérieur des crochets SCSS .d-header, ajoutons ce code imbriqué.
.d-header {
// ...code précédent
.d-icon {
color: var(--primary-low-mid);
}
}
Cela a l’air bien, mais un œil averti remarquera que la hauteur accrue de l’en-tête nous a laissé moins d’espace entre lui et le reste des éléments du forum Discourse !
L’espace entre la zone principale et l’en-tête est contrôlé par la cible #main-outlet. Augmentons cet espace un peu en ajoutant ce qui suit au 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 ciblons .select-kit-header pour leur donner un rayon de bordure identique, ainsi qu’une couleur d’arrière-plan plus claire.
En cliquant sur l’un ou l’autre de ceux-ci, un menu déroulant s’ouvre.
Actuellement, il a également des coins durs, alors ajoutons quelques styles pour les arrondir 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 look 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/ID nous devons cibler pour 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 cette entrée est située à 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 supérieure et inférieure, ainsi qu’un certain remplissage appliqué. Nous voulons uniquement modifier le style de la bordure supérieure.
Ajoutez le code suivant imbriqué dans le .select-kit-body scss d’auparavant.
.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’une UL avec une classe de "nav nav-pills ..."
Retournons dans notre fichier common.scss, sous la section précédente, mais toujours imbriqué dans 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 faire ressembler notre lien actif à ceci :
C’est bien, mais j’aimerais que la bordure inférieure ne s’étende que jusqu’au texte. Pour ce faire, au-dessus de la ligne &.active {, ajoutons ce qui suit, ce 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);
}
Donc 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 sous de nombreuses formes et tailles. Vous pouvez voir un assortiment d’entre eux dans le Guide de style dans la section Boutons.
J’aimerais changer la plupart des boutons de ce thème pour qu’ils soient arrondis avec un style personnalisé. Cela changera le bouton + Nouveau sujet, ainsi que d’autres boutons sur tout le site.
Au 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 concernant le style des boutons et pourquoi il est important de tester tous vos designs.
Cliquez sur un sujet dans l’aperçu de votre 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 de sujets. Vous verrez que notre style de bouton a affecté certaines choses que nous n’aurions 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 de SASS/CSS plus complexe, mais nous pouvons faire en sorte que notre code :not() n’affecte pas ces boutons. 
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, cela a très bien fonctionné… mais attendez ! Maintenant, il y a ce étrange 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 étrange le bouton de fermeture de la fenêtre modale. En cliquant sur n’importe quoi qui ouvre une fenêtre modale, vous pourrez voir cela, ou encore plus facile, 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)
Passons à la suite…
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é avec le style de la partie supérieure de notre forum.
Où aller à partir d’ici
Ce guide visait à 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’idées 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 n’utilisant que SCSS. Si vous souhaitez aller encore plus loin dans votre développement, je vous recommande de lire les articles liés en haut de cet article.
N’hésitez pas à poser des questions et je ferai volontiers de mon mieux pour vous aider, ou vous orienter dans la bonne direction.
Ce document est versionné - suggérez des modifications sur github.