This guide explains how to post code or preformatted text in Discourse using Markdown, BBCode, and HTML formats.
Required user level: All users
Have a line of code you need to share? Maybe you need to share an error log from your site? Reading unformatted code can be challenging, especially if the code depends on spacing or contains special characters that Discourse transforms.
Summary
In this guide, you’ll learn:
- How to format inline code.
- How to format entire lines of code.
- How to format blocks of code.
- How to use BBCode and HTML for code formatting.
- How to disable automatic code styling.
Inline code formatting
To format a specific section of text, use a single backtick on each side of the code. This can be done within regular text, or when the code is on its own line. Inline formatting does not apply any automatic code formatting (see below), and only applies the “code style” to the text between backticks.
Example 1:
Typing:
`This is a line of code`
Produces:
This is a line of code
Example 2:
Typing:
Here’s some text with `a bit of code` inside!
Produces:
Here’s some text with a bit of code inside!
Entire line code formatting
To format an entire line, add 4 spaces at the start of a line. All text until the next line break will be code.
Example:
Typing:
All text after 4 spaces will be formatted.
Produces:
All text after 4 spaces will be formatted.
Block code formatting
While you can use the 4-space method to produce multiple lines of code, this can be tedious, especially if you are copying and pasting and need to type 4 spaces on multiple lines of text.
Instead, use 3 backticks (```) on their own line above and below your code. Be sure there are no spaces on the lines with the backticks, or this will not work.
Example:
Typing:
```
public class CodeFormatting {
public static void main(String[] args) {
System.out.println("I can format code now!");
}
}
```
Produces:
public class CodeFormatting {
public static void main(String[] args) {
System.out.println("I can format code now!");
}
}
BBCode and HTML
In addition to Markdown, Discourse supports a subset of BBCode and HTML.
For HTML, use the <pre> and <code> tags:
<pre><code>
public class CodeFormatting {
public static void main(String[] args) {
System.out.println("I can format code now!");
}
}
</code></pre>
For BBCode, use the [code] tag:
[code]
public class CodeFormatting {
public static void main(String[] args) {
System.out.println("I can format code now!");
}
[/code]
Specifying the Programming Language
By default, Discourse detects the language of your code and styles it accordingly.
To manually specify the programming language for a code block, type the name of the language right after the first set of backticks:
``` your_language
# Your code here
Example
To specify Ruby:
Type:
``` ruby
3.times do |stuff|
stuff.do
end
```
Produces:
3.times do |stuff|
stuff.do
end
The language must be one of the highlighted languages configured for syntax highlighting on your site. The default list can be found on GitHub.
You can also set the default code language with the default code lang site setting.
Suppressing highlighting
If you want to prevent any syntax highlighting, you can use text as the language:
Example
Typing:
``` text
Your text to NOT highlight here
Produces:
Your text to NOT highlight here
Best practices
- Always ensure your inline code is framed with single backticks for clarity.
- Use block code formatting for sharing larger snippets of code.
- Avoid automatic code styling when sharing text or logs that do not benefit from language-specific styling.
- Specify the language if automatic detection is not recognizing your code correctly.
Additional resources
- Configure which programming languages are available for syntax highlighting
- Selecting the programming language used in code blocks
- Supported Formatting In Posts (markdown, BBCode, and HTML)
- Interactive Markdown Guide
Last edited by @hugh 2024-06-27T00:44:26Z
Check document
Perform check on document: