Posting code or preformatted text

Documentation Using Discourse
1

:bookmark: This guide explains how to post code or preformatted text in Discourse using Markdown, BBCode, and HTML formats.

:person_raising_hand: 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

Last edited by @hugh 2024-06-27T00:44:26Z

Check documentPerform check on document:
11 Likes