Requisitos
Para poder usar essas dicas e truques, você precisa ser administrador de uma instância do Discourse auto-hospedada ou de um plano hospedado pelo Discourse superior ao Básico.
Introdução
O Discourse suporta vários métodos para formatar e personalizar o conteúdo de uma postagem. Você pode encontrar a lista aqui:
Mas, às vezes, você vai querer algo mais específico, por exemplo, um link que pareça um botão.
É esse tipo de modificação que aprenderemos aqui.
A lógica
Vou explicar brevemente a lógica por trás disso, mas você pode pular para o próximo passo e ir direto para um exemplo prático 
O Discourse permite qualquer atributo HTML que comece com data- no conteúdo de uma postagem.
Esses são os atributos que usaremos com CSS para personalizar nosso conteúdo.
Vou chamá-los de atributos data- neste tutorial
Uma maneira de criar elementos com esses atributos é usar uma tag semelhante ao BBcode: [wrap], à qual adicionaremos um valor de nossa escolha. Aqui escolhemos “button” (isso poderia ser qualquer outra coisa, até mesmo o nome do seu cachorro 
):
[wrap=button]algum texto[/wrap]
Isso resultará em um elemento HTML com o seguinte atributo: data-wrap="button".
Primeiro exemplo: um fundo rosa
Vamos começar com um exemplo prático. Criaremos texto com um fundo rosa.
Como elemento bloco
Em sua postagem, em uma linha vazia, escreva:
[wrap=pink]texto rosa[/wrap]
Isso criará um elemento div com o atributo data-wrap="pink".
Em seguida, adicione o seguinte CSS ao seu tema.
Vá para Painel de Administração → Personalizar → Temas → seu tema → Editar CSS/HTML → CSS.
Cole o seguinte código CSS dentro:
[data-wrap="pink"] {
background: pink;
}
Em seguida, clique no botão Salvar.
Volte para sua postagem e veja o resultado:
Sim, já está lindo 
Você notará que o fundo cobre toda a largura da postagem. Como nosso wrap é o único elemento em sua linha, ele gera um elemento de bloco.
Você pode aprender mais sobre a diferença entre elementos HTML de bloco e inline aqui: HTML Block and Inline Elements.
Se você quiser que seu fundo rosa apareça em várias linhas (ainda como um bloco), precisará que ambas as tags [wrap] não tenham nenhum outro conteúdo ou texto na mesma linha:
[wrap=pink]
texto rosa
texto rosa
texto rosa
texto rosa
[/wrap]
Isso ficará assim:
Como elemento inline
Agora, vamos adicionar algum texto antes da [wrap], ou depois, ou ambos 
. Por exemplo:
Aqui está algum [wrap=pink]texto rosa[/wrap] e é incrível ✨
Aqui está o resultado:
Se houver texto ou outros elementos na mesma linha que uma das suas tags [wrap], ela gerará um elemento inline.
Segundo exemplo: um link com aparência de botão.
Brincar com a tag [wrap] às vezes pode levar a resultados indesejados por vários motivos, um deles sendo que ela pode ser um elemento de bloco ou inline dependendo do contexto.
Portanto, descreveremos dois métodos diferentes que alcançam o mesmo resultado, mas você poderá escolher o que mais lhe convier 
Um link de botão inline com [wrap]
A sintaxe para criar um link usando markdown é: [algum texto](https://algum-link.etc).
Para personalizar o texto e fazê-lo parecer um botão, inseriremos o wrap dentro dos colchetes. Aqui está um exemplo:
Este [[wrap=button]link legal[/wrap]](https://discourse.org/) é um botão azul 🐳 !
Não comentaremos sobre o que esse código gera. Você sabe que, como escreveu [wrap=button], terá que mirar em [data-wrap="button"] no seu CSS.
Então, vamos lá, vamos adicionar um CSS elegante para deixá-lo bonito! 
[data-wrap="button"] {
display: inline-block;
padding: 0.5em 1em;
background: DodgerBlue;
color: White;
}
Não detalharemos as regras de CSS aqui. Existem muitos recursos de CSS na Internet, então se você quiser fazer modificações mais específicas, precisará estudá-las primeiro.
O resultado 
:
Ficou bom, né?
Um link de botão inline com conteúdo HTML regular
Como o Discourse aceita código HTML, podemos decidir não usar as tags [wrap] e usar HTML com um atributo data-. Neste exemplo, usaremos a sintaxe regular do Markdown para o link e o envolveremos com tags <span>.
Não podemos usar diretamente uma tag de link <a> porque é uma exceção e não permitirá nenhum atributo data-.
Escreva:
Este <span data-button>[link](https://discourse.org/)</span> é um botão verde 🐸 !
Isso gerará um link dentro de uma tag <span> com um atributo data-button, o que significa que o CSS será um pouco mais complicado. Teremos que mirar tanto em data-button quanto no link:
[data-button] {
display: inline-block;
padding: 0.5em 1em;
background: ForestGreen;
a {
color: White;
}
}
E aqui está o resultado!
Para ir além
Uma lista personalizada usando [wrap]
As tags [wrap] e os atributos data- podem ser usados em muitos contextos e você pode personalizar conteúdo mais avançado. O limite é principalmente seu conhecimento de CSS (e HTML, em menor grau).
Vou dar um único exemplo sem explicação, personalizando uma lista em que cada elemento será precedido por um emoji de gato:
Texto:
[wrap=cat]
- Felix
- Garfield
- Gato do Nat
[/wrap]
CSS:
[data-wrap="cat"] ul {
list-style: none;
li:before {
content: "🐈";
margin-right: 0.25em;
}
}
Resultado:
Usando as variáveis de cor do seu próprio tema
Se você permitir que os usuários usem diferentes temas ou cores, suas modificações podem não ficar boas para todos, especialmente se houver opções entre esquemas de cores claros e escuros.
Uma boa prática é usar as variáveis de cor do Discourse em vez de cores “hardcoded” como red, #FF0000 ou rgb(255,0,0).
Aqui está um exemplo em que a cor de fundo do botão usará a cor primária da paleta atual e o texto usará a cor secundária:
Texto:
Este [[wrap=button]link legal[/wrap]](https://discourse.org/) é um botão 🌈 !
CSS:
[data-wrap="button"] {
display: inline-block;
padding: 0.5em 1em;
background: var(--primary);
color: var(--secondary);
}
Veja como ficará para um usuário usando o esquema de cores Solarized Light:
E se usarem o esquema de cores Solarized Dark:
Conclusão
Agora você tem o básico para criar elementos personalizados usando o elemento [wrap] e os atributos data-.
Para fazer personalizações mais avançadas, aprender CSS é primordial. Você encontrará muitos tutoriais na Internet.
O seguinte guia do Discourse também pode ser útil: Making custom CSS changes on your site.
Usar as ferramentas de desenvolvedor do seu navegador também mostrará facilmente a lista das variáveis de cor do seu Discourse e como cada uma se parece:
Sinta-se à vontade para sugerir qualquer modificação para este guia!
Este documento está sob controle de versão - sugira alterações no github.
