How to format your forum posts

avbentem · July 31, 2022, 12:16pm

The Docker forum is using Discourse, which supports several ways to format your posts:

Markdown; see commonmark.org/help for an interactive tutorial
BBCode
A small selection of HTML
Any combination of the above

Blank lines for formatting and readability

Quite often you’ll need an empty line above specific formatting to make it work.

You also need to type blank lines to create proper paragraphs; just pressing Return once and then typing a new block of text right below a previous block only creates a so-called line break. That not only makes text harder to read, but also is bad practice for accessibilty.

Leaving one blank line between two blocks of texts, like done here, nicely creates a new paragraph with a minimum extra whitespace. That looks good on both mobile and in a regular desktop browser.

Paragraph vs line break

Not convinced about that blank line for a proper paragraph?

Below is the same text as above, but without blank lines between paragraphs. Make sure to resize your browser window to see how things may look on different screen sizes of regular browsers, and remember some may be using a screen reader instead.
Quite often you’ll need an empty line above specific formatting to make it work.
You also need to type blank lines to create proper paragraphs; just pressing Return once and then typing a new block of text right below a previous block only creates a so-called line break. That not only makes text harder to read, but also is bad practice for accessibilty.
Leaving one blank line between two blocks of texts, like done here, nicely creates a new paragraph with a minimum extra whitespace. That looks good on both mobile and in a regular desktop browser.

Toolbar

The toolbar above the editor’s text input helps create mostly Markdown posts:

Editor toolbar842×62 2.3 KB

To apply formatting to parts of your post, first select the text you want to format and then click one of the toolbar buttons.
See the button’s tooltip for some hints. From left to right: quote post you’re replying to, bold, emphasis (italic), hyperlink, blockquote, preformatted text, upload an image or file, bulleted list, numbered list, emoij, date/time, other options (such as hidden details).

Dockerfiles, Compose files, logs and code

Please don’t post text as images. Those are hard to read in screen readers and on smaller screen sizes, are not found when searching the forum, and make it hard to copy/quote parts into an answer.

When posting code as text, formatting is important:

Whitespace (especially indentation) often matters in code, and also in YAML files. But whitespace is lost when not formatting properly.
Erroneous interpretation of < and > as <html elements> may result in parts of the text getting hidden.
Excessive interpretation of Markdown formatting (especially # for headers, and dashes for lists) may simply make your code impossible to read.

There are many easy options to format your code or logs:

Surround inline code in backticks; type `code`, or select some text and use the toolbar’s </> button, to get code.

“Markdown fenced code blocks”; type 3 backticks above and below your text, or select multiple lines of text and use the </> toolbar button:

Here is my `Dockerfile`:

```
FROM node:12-alpine
RUN apk add --no-cache python2 g++ make
WORKDIR /app
COPY . .
RUN yarn install --production
CMD ["node", "src/index.js"]
EXPOSE 3000
```

And my `docker-compose.yaml` file:

```
version: "3.9"  # optional since v1.27.0
services:
  web:
    build: .
    ports:
      - "8000:5000"
    volumes:
      - .:/code
      - logvolume01:/var/log
    links:
      - redis
  redis:
    image: redis
volumes:
  logvolume01: {}
```

Above you may also notice that long code blocks get vertical scroll bars to avoid very tall posts.

output

Here is my Dockerfile:

FROM node:12-alpine
RUN apk add --no-cache python2 g++ make
WORKDIR /app
COPY . .
RUN yarn install --production
CMD ["node", "src/index.js"]
EXPOSE 3000

And my docker-compose.yaml file:

version: "3.9"  # optional since v1.27.0
services:
  web:
    build: .
    ports:
      - "8000:5000"
    volumes:
      - .:/code
      - logvolume01:/var/log
    links:
      - redis
  redis:
    image: redis
volumes:
  logvolume01: {}

If automatic highlighting is very wrong, try adding a language specification after the 3 opening backticks. Like ```yaml for Compose files, and likewise ```json, ```bash, ```python and many more. (Not all code highlighting works properly on this Docker forum, like ```dockerfile should be supported, but somehow it’s not.)

Or use ```text to suppress any highlighting:

```text
## some log output
without highlighting
<here>
```

Or, without automatic highlighting, indent the code with 4 spaces:

Here is my Compose file:

    services:
      web:
        build: .
        ports:
          - "8000:5000"

output

Here is my Compose file:

services:
  web:
    build: .
    ports:
      - "8000:5000"

Or: use BBCode [code] above your code or logs, and [/code] below it.

Hiding details

If you have many details, you can collapse them to avoid a very long post, using the “Hide Details” option in the “gear” icon in the toolbar, or by typing:

<details>
<summary>Click to see the full logs</summary>

```text
This text will be hidden,
until clicked
```
</details>

[details=Click to see the full logs]
```text
This text will be hidden,
until clicked
```
[/details]

The first needs a blank line before any special formatting (like before the ```text in the example). Both will will get you the following:

Click to see the full logs

This text will be hidden,
until clicked

Quotes and attribution

When quoting text from others, attribution is required. Also make clear it’s a quote, not your own text, by prefixing with > or selecting the text and clicking the [”] toolbar button:

I found this on https://stackoverflow.com/a/30173220/:

> The docker `exec` command is probably what you are looking for; this will let you run arbitrary commands inside an existing container. For example:
>
>     docker exec -it <mycontainer> bash

output

I found this on How do I get into a Docker container's shell? - Stack Overflow

The docker exec command is probably what you are looking for; this will let you run arbitrary commands inside an existing container. For example:
docker exec -it <mycontainer> bash

URLs

URLs are replaced with the description that Discourse gets from their HTML metadata, most often its <title>. If that is not a good summary, then either explicitly define your own, or surround with <...> to suppress the automatic link title:

- See https://docs.docker.com/desktop/
- See [the Desktop documentation](https://docs.docker.com/desktop/)
- See <https://docs.docker.com/desktop/>

output

If a line only holds a URL, then that may introduce a so-called “onebox” preview. That may work nice for, say, GitHub but may not add much for other sites:

https://docs.docker.com/desktop/
https://github.com/docker/compose/blob/cc5b72b11dc3a55609edda005e7ed493622cf568/README.md?plain=1#L54-L66

output

github.com

docker/compose/blob/cc5b72b11dc3a55609edda005e7ed493622cf568/README.md?plain=1#L54-L66


      
          A Compose file looks like this:
          
          ```yaml
          services:
            web:
              build: .
              ports:
                - "5000:5000"
              volumes:
                - .:/code
            redis:
              image: redis
          ```

Image resizing

Images have a Discourse-specific Markdown option to scale down the preview size; add a percentage such as ,10% after the image size that is already added when uploading an image:

![Docker logo|618x500, 10%](upload://pp7tVuTdjM1QZm4talenzRlJD0Z.png)

This gets you a smaller image that is clickable to see the full version.

Markdown

See Markdown Reference for a nice overview. It’s really easy; just a few of its options:

Just type, **use plenty of whitespace** and [link your sources](https:/docs.docker.com)!

- An unordered list.
- Item B.    

Or:

1. An ordered list
    1. Nested item
    2. Nested item

2. Item 2.
    - Nested unordered list

3. Item 3.

    Nested paragraph.

    > Nested quote.

    ```
    Nested code
    ```

> A quote
>
>     with nested code

HTML

Only a few tags are supported; other HTML may simply become invisible. So when code includes < and > then ensure to use inline code formatting like `<some-option>` to see <some-option>.

BBCode

[b]strong[/b]
[i]emphasis[/i]
[u]underlined[/u]
[s]strikethrough[/s]
[ul][li]option one[/li][/ul]
[quote="eviltrout"]They said...[/quote]
[quote="eviltrout, post:1, topic:2"]They said...[/quote]
[img]http://eviltrout.com/eviltrout.png[/img]
[url]http://bettercallsaul.com[/url]
[email]eviltrout@mailinator.com[/email]
[code]\nx++\n[/code]

Editing your posts

You can use the pencil icon below your post to edit it, if it’s not too old.

If you want to alert future readers about an error in your post, but do not want to remove it altogether as others already responded, then consider using ~~strikethrough~~ to ~~strike some text that was wrong~~.

If you are editing quickly after the last time you saved your post, it will not be marked as edited. But after about 5 minutes, or if others meanwhile responded, or if the edit is significantly large, a pencil icon will appear at the top-right of your post to warn other readers about the edit. This will change color if a post was edited recently. Readers can click it to see the history.

If you accidentally included sensitive details (personal details, passwords) then use the flag icon below a post to notify a moderator, who can then hide the troublesome revision from being viewed.

zavertis · March 24, 2023, 8:11am

Good morning Sir, Madame,

Thank for these recommandations.

Regards,