Community, first steps: Code, config, log block formatting in topics and replies

Sharing code, config, log blocks or preformatted text

The Discourse forum platform uses Markdown for topics and replies, similar to GitLab. You can use the UI editor to write and live preview. Sometimes, there is the need to share code snippets, many log lines, configuration lines, etc.

The icon for preformatted text allows you to add a code block, over multiple lines, enclosed with three backticks each.

image

The advantages of these blocks are

  1. Increased readability: Readers can follow your questions and descriptions, and inspect the code/config/logs on-demand
  2. Indent and spaces are kept, this is important for YAML, Python, etc.
  3. Syntax highlighting and formatted keywords to aid reading and focus.

More Tips

  1. Prefer text in code blocks over screenshots. Everyone can copy-paste the text to either start a new internet search on their own or open the source code of GitLab and involved components to look for the origin.
    1.1. When you think it is helpful to see the code block in its “natural” environment (e.g. a terminal, console, frontend, etc.), please attach both, the code block and a screenshot.
  2. Review the code blocks for sensitive information before posting.
    2.1. Replace hostnames with example.com, or if multiple, server1.example.com, server2.example.com, etc.
    2.2. Replace login name with redacted-user, password/tokens with redacted
    2.3. Staff team members can help remove sensitive information, or will actively do and let you know when they see it. The diff between edits is not publicly visible.

Optional Details

Sometimes, additional details in a code block, or multiple lines can be helpful. In order to not make everyone scroll endlessly and potentially miss important information, you can use the [defails=Summary]...[/details] syntax.

[details=This text is shown and encourages to learn more. Results, Summary, etc.]
Longer context, code blocks, etc. 
[/details]
This text is shown and encourages to learn more. Results, Summary, etc.

Longer context, code blocks, etc.

Tip: The code styling examples below use the same method to hide the results by default.

Code Styling

Discourse supports a number of common languages, such as json, yaml, markdown, sql, bash, cpp, javascript, python, ruby, perl, php, go, rust, typescript, powershell.

Below are a few examples.

YAML

```yaml
image: python:3.10

build:
  script: 
    - echo "Hello from the One DevOps Platform 🦊" 
```
Result
image: python:3.10

build:
  script: 
    - echo "Hello from the One DevOps Platform 🦊" 

json

```json
{
  "key": "value"
}
```
Result
{
  "key": "value"
}

Ruby

```ruby
def devops_platform?(one)
  return true
```
Result
def devops_platform?(one)
  return true

Text

```text
This is preformatted text. 
```
Result
This is preformatted text. 

Diff

You can also share diffs.

```diff
-Old line
+New line 
```
Result
-Old line
+New line 
2 Likes

This topic is also added on top of the FAQ, the single source of truth for all helpful resources. FYI @iwalker @snim2

4 Likes