This reference guide details all the formatting options available in Discourse posts, including markdown, BBCode, and HTML. It specifies what is supported and provides resources where you can see examples.
Required user level: All users
Understanding supported formatting in posts
While plain text is sufficient for most replies, Discourse allows users to enhance the formatting of their posts by using markdown, BBCode, and HTML. This guide explains what types of formatting are supported and how you can use them effectively.
You can also practice some of the basics in an interactive tutorial by sending a personal message to @discobot here or on any Discourse site.
Summary
This guide covers:
- Supported markdown syntax
- Supported BBCode tags
- Supported and safe HTML tags and attributes
Best practices
- Use markdown primarily for its simplicity and readability.
- Mix markdown and BBCode only when necessary, and keep usage consistent.
- Limit the use of HTML to simple, safe tags to avoid formatting issues and ensure posts are secure.
Supported markdown
Discourse uses markdown-it for its markdown implementation.
Some commonly used markdown features include:
-
Bold:
**text** -
Italic:
*text* -
Link:
[title](https://example.com) -
Inline code:`code` -
Highlight:
<mark></mark> - Code block:
``` code block ```
In longer posts (like this one), it can also be helpful to add structure using headings:
# Heading 1
## Heading 2
### Heading 3
Note: when an image is uploaded, the markdown syntax to reference the image will automatically be generated.
For a full list of markdown features, please refer to the interactive guide.
Supported BBCode
Discourse supports a subset of common BBCode tags, some of which are generated automatically to support special formatting, for example when you quote a post in your reply:
[quote="user"]quoted text[/quote]
You can also use BBCode to mark hide text as a spoiler or as details
spoiled text
[spoiler]spoiled text[/spoiler]
click to expand
hidden text
[details="click to expand"]hidden text[/details]
BBCode tags for simple formatting supported by markdown or are also supported:
[b]strong[/b][i]emphasis[/i][u]underlined[/u][s]strikethrough[/s][ul][li]option one[/li][/ul][img]http://example.com/image.png[/img][url]http://example.com[/url][code]code[/code]
For a complete list of supported BBCode tags and examples, check the Discourse BBCode tests.
Supported HTML
Discourse supports a safe subset of HTML. While you can mix HTML with markdown, only specific HTML tags and attributes are allowed to ensure security and consistent styling.
Some of the allowed HTML tags include:
<a href="https://example.com">link</a><strong>bold text</strong><em>italic text</em><ul><li>list item</li></ul><img src="https://example.com/image.png" alt="description">
For a detailed list of allowed HTML tags and attributes, refer to Discourse’s allow-list.
Note: Inline styles, like <span style="color:red">colored text</span>, are not supported. For custom styles, see customize post contents.
Common issues and solutions
- BBCode or HTML tags not working: Ensure the tags you are using are part of the supported subset.
- Inline styles being stripped: Discourse does not support inline styles for security reasons. Use custom styles or plugins if necessary.
- Formatting changes on pasting from other editors: Some rich-text formats may not render correctly. Use markdown to format text consistently.
FAQs
Q: Can I use tables in Discourse?
A: Yes, you can use markdown to create tables. For more information, see this guide on tables.
Q: Why isn’t my inline style working?
A: Discourse does not support inline styles in HTML for security reasons. Consider using custom BBCode or the Discourse custom styling guide.
Q: Can I add custom BBCode tags?
A: Yes, you can add custom BBCode tags. Refer to the Discourse BBCode plugin for more information.
Additional resources
- Interactive markdown guide: https://markdown-it.github.io/
- Customize post contents: Customize posts' contents with your own styles
- Discourse BBCode plugin: Discourse BBCode
Last edited by @MarkDoerr 2024-07-11T00:31:08Z
Check document
Perform check on document:
