Então você está interessado em criar seu próprio tema para o Discourse? Você chegou ao tópico certo 
Este guia será mais focado nos aspectos SCSS/CSS de trabalhar com temas no Discourse. Se você também tem conhecimento em JS/EmberJs/Handlebars, pode ir ainda mais fundo consultando este guia.
Vou descrever meu método pessoal de design e criação de temas no Discourse. Como na maioria das coisas, existem MUITAS maneiras de implementar seus próprios designs. Gosto de usar bastante as ferramentas de inspeção ao criar temas e mostrarei algumas vezes como faço isso neste post.
Configurando o Ambiente para Criação de Temas
Por favor, leia o Guia para Iniciantes sobre o Uso de Temas no Discourse, bem como a Estrutura de Temas… antes de continuar. Um conhecimento profundo não é necessário neste momento, mas esses artigos lhe darão um pouco mais de familiaridade antes de começar.
Para trabalhar da melhor forma possível com temas no Discourse, sugiro configurar o seguinte para oferecer a você o processo de design mais rápido e eficiente. Essas etapas permitirão que você veja suas alterações conforme as faz, sem precisar ‘salvar’ e atualizar o painel de administração de um site Discourse.
É perfeitamente possível seguir este guia usando o console de administração (desde que você tenha acesso de nível de administrador a um fórum Discourse.)
- Instale o Discourse Theme CLI e leia aquele tópico para entender o que ele pode fazer.
- Obtenha uma Chave de API em https://discourse.theme-creator.io/
- Faça login com sua conta Meta
- Clique em Meus Temas
- Clique em Chave de API
- No modal de popup, clique em Gerar Chave de API & copie a chave gerada para você (usaremos isso em breve)
Executando o Discourse Theme CLI
Com o Discourse Theme CLI instalado e sua Chave de API pronta, abra seu editor de texto ou janela de terminal preferidos e altere seu diretório de trabalho para onde deseja configurar a pasta do seu tema.
Uma vez lá, execute o seguinte comando discourse_theme new seu_nome_de_tema e preencha as solicitações da seguinte forma:
-
Como você gostaria de chamar seu tema? Escolha o nome do seu tema
-
Você gostaria de começar a monitorar este tema? Sim
-
Qual é a URL raiz do seu site Discourse?
https://discourse.theme-creator.io/ -
Você gostaria de armazenar o nome deste site em…? Sim
-
Qual é sua Chave de API? Insira a chave de API que você recuperou do criador de temas
-
Você gostaria de armazenar esta chave de API…? Sim
-
Escolha Criar e sincronizar com um novo tema quando solicitado
-
Escolha Não fazer nada quando solicitado sobre componentes de temas filhos
Se tudo funcionou corretamente, você agora deve ser capaz de navegar para Meus Temas em https://discourse.theme-creator.io/ e ver seu novo tema na lista de temas à esquerda.
Para visualizar essas alterações em tempo real, clique no nome do seu tema e, na parte inferior da área de informações, clique em Pré-visualizar
O Theme CLI também está agora monitorando quaisquer alterações no diretório recém-criado e salvará, bem como atualizará o tema no theme-creator a cada alteração.
Primeiros Passos
O Discourse Theme CLI criou uma estrutura de tema para nós dentro da pasta com o nome que especificamos no comando que executamos anteriormente. Muitos arquivos são gerados que não usaremos, então vamos prosseguir e excluir tudo, exceto o seguinte:
common/common.scss
desktop/desktop.scss
mobile/mobile.scss
about.json
Dentro do diretório, execute também rm -rf .git para remover o rastreamento de versão do git, pois não será necessário para este guia.
Seu diretório de tema agora deve parecer com isto:
Vale notar que os estilos que adicionamos a esses arquivos serão renderizados em seus respectivos casos de uso. Estilos em common.scss serão aplicados a desktop + mobile, enquanto estilos em desktop.scss serão aplicados apenas à navegação em desktop, e aqueles em mobile.scss aplicarão apenas às visualizações móveis.
Olá Mundo (em cor)
O Discourse usa SCSS para seu estilo, então, para aproveitar ao máximo os estilos, você pode querer se familiarizar com SASS, mas se não, ainda será capaz de acompanhar este guia.
Ok, agora para chegar ao que todos estávamos esperando… CRIAÇÃO DE TEMAS!
Neste momento, nosso about.json atualmente não possui nenhum esquema de cores definido, então cole o seguinte código nessa seção e salve.
{
"name": "meu tema",
"about_url": null,
"license_url": null,
"assets": {},
"color_schemes": {
"Padrão": {
"primary": "222222",
"secondary": "ffffff",
"tertiary": "0088cc",
"quaternary": "e45735",
"header_background": "ffffff",
"header_primary": "333333",
"highlight": "ffff4d",
"danger": "e45735",
"success": "009900",
"love": "fa6c8d"
}
}
}
Se você tiver seu navegador aberto, não verá nenhuma alteração entrar em vigor, pois este é o esquema de cores padrão usado quando nenhum esquema está presente.
Visão Geral do Tema
Para ter algo para realmente implementar neste guia, vou guiá-lo na criação de um tema simples baseado nesta paleta de cores.
Alterando a Cor de Fundo + Cor do Texto Primário
Vamos fazer algo muito simples. Vamos alterar o valor "secondary" do nosso esquema de cores atual. Vamos alterá-lo para "secondary": "EEF4F7" (isso altera a cor de fundo.) Vamos também alterar o valor "primary" para "203243".
Com apenas essa linha, já alteramos a aparência e a sensação do nosso fórum. Muito pode ser personalizado apenas editando as cores no esquema de cores.
Uso do Esquema de Cores
Todas as seguintes chaves são definidas no arquivo about.json sob o nome do esquema de cores correspondente. Essas descrições são uma boa referência para ajudá-lo a entender qual é o objetivo principal de cada nome de variável:
| Cor | Descrição |
|---|---|
| primary | Maioria dos textos, ícones e bordas |
| secondary | A cor de fundo principal e a cor do texto de alguns botões |
| tertiary | Links, alguns botões, notificações e cor de destaque |
| quaternary | Links de navegação |
| header_background | Cor de fundo do cabeçalho do site |
| header_primary | Texto e ícones no cabeçalho do site |
| highlight | A cor de fundo de elementos destacados na página, como postagens e tópicos |
| danger | Cor de destaque para ações como excluir postagens e tópicos |
| success | Usado para indicar que uma ação foi bem-sucedida |
| love | A cor do botão de curtir |
Cada uma dessas variáveis está disponível para uso dentro de nossos arquivos SCSS da seguinte forma.
body {
background-color: var(--primary);
}
Outras versões de cada cor também são criadas para nosso uso. Coisas como var(--primary-medium) ou var(--primary-very-low) podem ser usadas para obter diferentes tons da mesma cor.
Vamos alterar as outras cores em nosso esquema de cores “Padrão” para corresponder a isto:
"Padrão": {
"primary": "203243",
"secondary": "EEF4F7",
"tertiary": "416376",
"quaternary": "5E99B9",
"header_background": "FaFaFa",
"header_primary": "EEF4F7",
"highlight": "86BDDB",
"danger": "8F393E",
"success": "70DB82",
"love": "FC94CB"
}
Você pode ver todas as variáveis disponíveis para uso em seus arquivos SCSS se clicar no link Guia de Estilo ao pré-visualizar seu tema no theme creator e depois clicar em Cores no menu à esquerda.
O Guia de Estilo é uma seção muito útil para olhar quando você está criando um tema personalizado. Cada Atom mostrará como certos elementos do Discourse parecerão com seus estilos aplicados.
Indo Mais Fundo
Com a seção anterior sob nosso controle, acho que é hora de irmos um pouco mais fundo no que pode ser feito no Discourse apenas com SCSS. (Dica: MUITO!)
Estilizando o Cabeçalho
Você notará que nossas alterações anteriores no esquema de cores deixaram algo a desejar em nosso cabeçalho. Os ícones são quase invisíveis!
O cabeçalho do Discourse inclui um container (com uma cor de fundo) para segurar um logotipo do site, bem como os ícones de navegação à direita. Todos esses podem ser personalizados.
A classe alvo para personalizar o cabeçalho é .d-header.
Em nosso arquivo common/common.scss, vamos adicionar o seguinte:
.d-header {
box-shadow: none;
border-bottom: 1px solid var(--primary-low-mid);
height: 5em;
}
Isso removerá a sombra de caixa padrão no cabeçalho, dará um pouco mais de altura e definirá uma borda inferior para nos dar alguma separação.
Para os ícones – Dentro dos colchetes SCSS .d-header, vamos adicionar este código aninhado.
.d-header {
// ...código anterior
.d-icon {
color: var(--primary-low-mid);
}
}
Isso está ficando bom, mas um olho atento notará que o aumento da altura do cabeçalho nos deu menos espaço entre ele e o restante dos elementos do fórum Discourse!
O espaçamento entre a área principal e o cabeçalho é controlado pelo alvo #main-outlet. Vamos aumentar esse espaçamento um pouco adicionando o seguinte ao final do seu arquivo common/common.scss.
#main-outlet {
padding-top: 6.5em;
}
Container de Navegação
O container de navegação inclui as seguintes partes.
A área mais à esquerda são os menus suspensos de filtro de categoria/tag, seguidos pelos links de navegação, terminando com o botão Novo Tópico.
Menu Suspenso de Categoria / Tag
Vamos fazer algumas alterações nesta área. Para fazer isso, adicione o seguinte ao seu arquivo common.scss.
.navigation-container {
.select-kit.combo-box {
.select-kit-header {
border-radius: 0.9em;
background-color: var(--header_background);
}
}
}
Aqui, visamos o .select-kit-header para dar a cada um um border-radius idêntico, bem como uma cor de fundo mais clara.
Clicar em qualquer um deles abre um menu suspenso.
Atualmente, ele também tem cantos duros, então vamos adicionar alguns estilos para arredondá-los, bem como alterar a cor de fundo para ser a mesma do cabeçalho.
.navigation-container {
.select-kit.combo-box {
// ...código anterior
&.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;
}
}
}
}
}
Isso resulta na seguinte aparência…
Se você olhar de perto, verá que nossas alterações deixaram uma pequena borda visível no canto superior direito da área de pesquisa.
Vamos corrigir isso olhando no inspetor do nosso navegador. Esta é sempre uma ferramenta super útil para aprender quais classes/IDs precisamos mirar para aplicar estilos corretamente.
Com o menu suspenso visível, clique com o botão direito na área de pesquisa e ‘Inspeccione’ o elemento no seu navegador.
Podemos ver que esta entrada está localizada dentro de um div com a classe select-kit-filter.
Se olharmos para as regras sendo aplicadas a este seletor, podemos ver que ele atualmente tem uma borda superior e inferior, bem como algum preenchimento aplicado. Queremos alterar apenas o estilo da borda superior.
Adicione o seguinte código aninhado no .select-kit-body scss de antes.
.select-kit.combo-box.category-drop,
.select-kit.combo-box.tag-drop {
.select-kit-body {
// ...código anterior
.select-kit-filter {
border-top: 0px;
}
}
}
Com isso, nosso código para estilizar o container de navegação deve ficar assim.
.navigation-container {
// Menu Suspenso de Categoria + Tag
.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;
}
}
}
}
}
Links de Navegação
Vamos adicionar alguns estilos para fazer com que esses links de navegação se pareçam com isto:
Vamos usar nosso inspetor novamente para descobrir o que devemos mirar aqui.
Podemos ver que nossos elementos de navegação estão dentro de um UL com a classe "nav nav-pills ..."
De volta ao nosso arquivo common.scss, abaixo da seção anterior, mas ainda aninhado dentro de navigation-container, vamos adicionar o seguinte:
.nav-pills {
& > li a {
&.active {
color: var(--tertiary);
background-color: var(--secondary);
border-bottom: 4px solid var(--tertiary);
}
}
}
Essa alteração mirará apenas nossos links com a classe active que são filhos de nav-pills. Essa alteração deve fazer com que nosso link ativo fique assim:
Isso está bem, mas gostaria que a borda inferior se estendesse apenas até o texto. Para fazer isso, acima da linha &.active {, vamos adicionar o seguinte, o que afetará todos os links A dentro das tags <li> de navegação.
// ...outro código
.nav-pills {
& > li a {
padding: 0;
margin-right: 20px;
color: var(--tertiary-high);
border-bottom: 4px solid transparent;
&.active {
// ...mais código
}
}
}
Agora, precisamos estilizar o efeito “hover” para ser o mesmo que o efeito “active”.
Sob nosso &.active anterior, vamos adicionar
&:hover {
color: var(--tertiary);
background-color: var(--secondary);
border-bottom: 4px solid var(--primary);
}
Então todo o nosso código de navegação agora deve ficar assim:
// 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);
}
}
}
Botões
Botões no Discourse vêm em muitas formas e tamanhos. Você pode ver uma variedade deles no Guia de Estilo na seção Botões.
Gostaria de alterar a maioria dos botões neste tema para serem arredondados com algum estilo personalizado. Isso alterará o botão + Novo Tópico, bem como outros botões em todo o site.
No final do nosso arquivo common.scss, vamos adicionar o seguinte:
.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;
}
}
Isso fará com que nossos botões fiquem assim:
Agora que nossos botões estão estilizados, gostaria de apontar algo sobre a estilização de botões e por que é importante testar todos os seus designs.
Clique em um Tópico na pré-visualização do seu site e, em seguida, pressione o botão responder em uma resposta de tópico ou no botão de resposta na parte inferior do fluxo de tópicos. Você verá que nossa estilização de botão afetou algumas coisas que talvez não tivéssemos em mente.
Não quero que esses botões de edição de texto sejam afetados pela minha estilização anterior. Isso requer um pouco de SASS/CSS mais complexo, mas podemos fazer com que nosso código :not() afete esses botões. 
Vamos adicionar esta linha de código na frente do nosso alvo .btn atual. Isso dirá aos nossos estilos para aplicar apenas a botões que não são filhos do .d-editor-button-bar.
:not(.d-editor-button-bar) > .btn
Ok, isso funcionou muito bem… mas espere! Agora há esse estranho rebelde fazendo a sua própria coisa.
Inspecionando isso no navegador, posso ver que este botão tem uma classe .select-kit-header porque, ao clicar nesta engrenagem, mais opções serão mostradas.
Agora que sabemos que NÃO queremos mirar neste botão, vamos adicionar mais funcionalidade :not() ao nosso código.
:not(.d-editor-button-bar) >
.btn:not(.single-select-header)
Isso selecionará todos os botões que NÃO são filhos do .d-editor-button-bar e não têm a classe .single-select-header. Sei que isso é um pouco confuso, mas dentro do Discourse, há muitas partes móveis, então às vezes a estilização precisa ser muito específica para afetar os elementos corretamente.
Também notei que nossa estilização atual afeta o botão de fechar modal de forma estranha. Clicar em qualquer coisa que abra um modal permitirá que você veja isso, ou ainda mais fácil, podemos navegar para a seção modal do Guia de Estilo.
Para corrigir isso, adicionarei outro alvo ao nosso código.
:not(.d-editor-button-bar) >
.btn:not(.single-select-header):not(.modal-close)
Seguindo em frente…
Vejo mais um botão que parece não ter sido afetado pelo nosso código. É o botão Acompanhamento localizado na parte inferior de um fluxo de postagens de tópico.
Adicionarei a seguinte linha, após uma vírgula, ao nosso código .btn atual.
:not(.d-editor-button-bar) >
.btn:not(.single-select-header):not(.modal-close),
.topic-notifications-button > .select-kit > .btn
Isso mirará o botão que aparece nesta seção corretamente e, por enquanto, terminamos de estilizar a área superior do nosso fórum.
Para onde ir a partir daqui
Este guia foi feito para arranhar a superfície de como você pode personalizar seu próprio tema para o Discourse. Espero que agora você tenha mais insights sobre como mirar áreas do aplicativo para suas próprias personalizações.
Lembre-se: MUITAS coisas podem ser personalizadas usando apenas SCSS. Se você quiser ir ainda mais fundo no seu desenvolvimento, recomendo ler os artigos vinculados no topo deste post.
Sinta-se à vontade para fazer perguntas e eu tentarei ajudá-lo ou apontá-lo na direção certa.
Este documento está sob controle de versão - sugira alterações no github.