Skip to main content
Version: Next

Markdown Guidelines

A guideline to writing markdown in a consistent manner.

Headers​

Avoid in-line code blocks in headers​

Headers should not include in-line code blocks.

✅ Good

## thin-edge.io info

❌ Bad

## `thin-edge.io` info

Don't end a subsection with a colon​

Headers (either headers or bold text acting as a header) does not need punctuation.

✅ Good

**Topic**

❌ Bad

**Topic:**

Code blocks​

Shell/console syntax highlighting​

Use the sh syntax highlight option for any console/terminal related code blocks.

✅ Good

```sh
tedge --help
```

❌ Bad

```console
tedge --help
```
```shell
tedge --help
```

Console output​

Console output should use the text syntax highlighter and should have a title block indicating that it is output.

You can use other syntax highlighting if the output is of another format (e.g. json).

✅ Good

```sh title="Output"
tedge --help
```

❌ Bad

```sh
tedge --help
```

✅ Good

```json title="Output"
{
   "text": "example"
}
```

❌ Bad: Incorrect syntax highlighting for the output

```sh
{
   "text": "example"
}
```

Avoid in-line code blocks for long commands​

In-line code blocks are not easy for users to copy the text from. Use a full code-block instead as these blocks are rendered with a "copy" button built-in.

✅ Good

**Topic**
   
```text
te/device/{child}///cmd/config_snapshot/1
```

❌ Bad

**Topic**
   
   `te/device/{child}///cmd/config_snapshot/1`

Systemd/journald service commands​

Don't use the .service suffix in calls to systemctl and journalctl.

✅ Good

```sh
sudo systemctl restart tedge-mapper-c8y
```

❌ Bad

```sh
sudo systemctl restart tedge-mapper-c8y.service
```

Set file path in title​

If the contents of a code block relate to the contents of a file, then the file path should be included in the title.

✅ Good

```toml title="file: /etc/tedge/tedge.toml"
[c8y]
url = "mytenant.cumulocity.com"

[mqtt]
bind_address = "127.0.0.1"
```

❌ Bad

```toml
[c8y]
url = "mytenant.cumulocity.com"

[mqtt]
bind_address = "127.0.0.1"
```