Requirements
To be able to use these tips and tricks, you need to be an administrator of either a self-hosted Discourse instance or a Discourse-hosted plan higher than Basic.
Introduction
Discourse supports several methods to format and customize a post’s contents. You can find the list here:
But sometimes, you’ll want something more specific, for example, a link that looks like a button.
This is the kind of modification we’ll learn here.
The logic
I’ll briefly explain the logic behind but you can go to the next step and jump into a practical example 
Discourse allows any HTML attribute starting with data- in a post’s content.
Those are the attributes we’ll target with CSS to customize our content.
I’ll call them data- attributes in this tutorial
One way to create elements with these attributes is a BBcode-like tag: [wrap], to which we’ll add a value of our choice. Here we choose “button” (that could be anything else, even the name of your dog 
):
[wrap=button]some text[/wrap]
This will output an HTML element having the following attribute: data-wrap="button".
First example: a pink background
Let’s start with a practical example. We’ll create text with a pink background.
As a block element
In your post, on an empty line, write:
[wrap=pink]pink text[/wrap]
It will create a div element having the attribute data-wrap="pink".
Then, add the following CSS to your theme.
Go to Admin panel → Customize → Themes → your theme → Edit CSS/HTML → CSS.
Put the following CSS code inside:
[data-wrap="pink"] {
background: pink;
}
Then click the Save button.
Go back to your post, and see the result:
Yes, it is already beautiful 
You’ll notice that the background covers the whole post width. Because our wrap is the only element on its line, it outputs a block element.
You can learn more about the difference between blocks and inline HTML elements here: HTML Block and Inline Elements.
If you want your pink background on multiple lines (still as a block), you’ll need both your [wrap] tags having no other content or text on the same line:
[wrap=pink]
pink text
pink text
pink text
pink text
[/wrap]
This will look like this:
As an inline element
Now, let’s add some text before the [wrap], or after, or both 
. For example:
Here is some [wrap=pink]pink text[/wrap] and it's awesome ✨
Here’s the result:
If text or other elements are on the same line as one of your [wrap] tags, it will output an inline element.
Second example: a link with a button’s appearance.
Fiddling with the [wrap] tag can sometimes lead to unwanted results for various reasons, one being that it can be a block or an inline element depending on the context.
So, we’ll describe two different methods that achieve the same result, but you’ll be able to pick the one that suits you the most 
An inline button link with [wrap]
The syntax to create a link using markdown is: [some text](https://some-link.etc).
To customize the text and make it appear like a button, we’ll insert the wrap inside the square brackets. Here’s an example:
This [[wrap=button]nice link[/wrap]](https://discourse.org/) is a blue button 🐳 !
We won’t comment on what this code outputs. You know that because you wrote [wrap=button], you’ll have to target [data-wrap="button"] in your CSS.
So, let’s go, let’s add some fancy CSS to make it pretty! 
[data-wrap="button"] {
display: inline-block;
padding: 0.5em 1em;
background: DodgerBlue;
color: White;
}
We won’t detail the CSS rules here. There are many CSS resources on the Internet, so if you want to do more specific modifications, you’ll have to learn about it first.
The result 
:
That looks good, right?
An inline button link with regular HTML content
Since Discourse accepts HTML code, we can decide not to use the [wrap] tags and use HTML with a data- attribute. In this example, we’ll use the regular Markdown syntax for the link and surround it with <span> tags.
We can’t directly use a link <a> tag because it’s an exception and won’t allow any data- attribute.
Write:
This <span data-button>[link](https://discourse.org/)</span> is a green button 🐸 !
It will output a link inside a <span> tag having a data-button attribute, which means the CSS will be a bit more complicated. We will have to target both data-button and the link:
[data-button] {
display: inline-block;
padding: .5em 1em;
background: ForestGreen;
a {
color: White;
}
}
And here’s the result!
To go further
A customized list using [wrap]
[wrap] tags and data- attributes can be used in many contexts and you can customize more advanced content. The limit is mostly your CSS knowledge (and HTML to a lesser extent).
I’ll give a single example without explanation by customizing a list in which each element will be prepended with a cat emoji:
Text:
[wrap=cat]
* Felix
* Garfield
* Nat's cat
[/wrap]
CSS:
[data-wrap="cat"] ul {
list-style: none;
li:before {
content: "🐈";
margin-right: 0.25em;
}
}
Result:
Using your own theme’s colors variables
If you allow users to use different themes or colors, your modifications may not look good for each one, especially if they have choices between light and dark color schemes.
A good practice is using Discourse’s color variables instead of “hardcoded” colors such as red, #FF0000 or rgb(255,0,0).
Here’s an example in which the button’s background color will use the primary color of the current palette, and the text will use the secondary color:
Text:
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);
}
Here’s how it will look for a user using the Solarized Light color scheme:
And if they use the Solarized Dark color scheme:
Conclusion
You now have the basics to create custom elements using the [wrap] element and the data- attributes.
To make more advanced customizations, learning CSS is primordial. You’ll find many tutorials on the Internet.
The following Discourse’s guide can also be of some help: Make CSS changes on Your Site.
Using the developer’s tools of your Internet Browser will also easily show you the list of your Discourse’s color variables and what each looks like:
Feel free to suggest any modification for this guide!
This document is version controlled - suggest changes on github.
Last edited by @JammyDodger 2024-05-25T10:13:36Z
Check document
Perform check on document:
