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:
-
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 getcode. -
“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 3000And my
docker-compose.yamlfile: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
```yamlfor Compose files, and likewise```json,```bash,```pythonand many more. (Not all code highlighting works properly on this Docker forum, like```dockerfileshould be supported, but somehow it’s not.)Or use
```textto 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 https://stackoverflow.com/a/30173220/:
The docker
execcommand 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
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:
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.