Markdown Style Guide

Code

Guide for code and code blocks.


# Code Blocks

Avoid indentation based code blocks, use fenced code blocks (opens new window) for multi line code.

This prevents malformed rendered output due to wrong indentation errors, increases the readability and allows the usage of language syntax highlighting (opens new window).

remark-lint: code-block-style (opens new window)

👍 Correct code for this rule:

```js
import React, { PureComponent } from "react";

class Awesome extends PureComponent {
  // ...
}

export default Awesome;
```

👎 Incorrect code for this rule:

```js
    import React, { PureComponent } from "react";

    class Awesome extends PureComponent {
      // ...
    }

    export default Awesome;
```

# Syntax highlighting

Explicitly declare the language for blocks containing code snippets, so that neither the syntax highlighter nor the next editor must guess.

remark-lint: fenced-code-flag (opens new window)

👍 Correct code for this rule:

```js
import React, { PureComponent } from "react";

class Awesome extends PureComponent {
  // ...
}

export default Awesome;
```

👎 Incorrect code for this rule:

```
import React, { PureComponent } from "react";

class Awesome extends PureComponent {
  // ...
}

export default Awesome;
```

# Escape newlines in terminal commands

Command snippets are intended to be copied and pasted directly into for example a terminal.

To protect the user from unintentional run the copied code due to a newline (interpreted by the terminal as Enter) use a single backslash at the end of the line.

👍 Correct code for this rule:

npx run docs:generate -- --template=plone --description="Plone is awesome" \
--elements="volto" --scale=20

👎 Incorrect code for this rule:

npx run docs:generate -- --template=plone --description="Plone is awesome" --elements="volto" --scale=20

# No shell code dollar sign

Avoid to use dollar sign ($) in shell code. It improves the readability and prevents error when users copy and paste the code.

To clarify the output of a command use for example a comment on the next line or optionally append it to the command on the same line, separated by a space.

remark-lint: no-shell-dollars (opens new window)

👍 Correct code for this rule:

echo "Plone is awesome!"

winter="Plone is awesome!"
echo $winter # Plone is awesome!

👎 Incorrect code for this rule:

$ echo "Plone is awesome!"

# Within lists

When using code blocks within lists make sure to use the correct indention to not break the list.

👍 Correct code for this rule:

- Plone
  ```jsx
  const Volto = <Scale amount=20 />;
  ```
- Guillotina

👎 Incorrect code for this rule:

- Plone
```jsx
const Volto = <Scale amount=20 />;
```
- Guillotina

# Inline

Use one (1) backtick character ` to create a inline code span which will render all wrapped content literally.

👍 Correct code for this rule:

Use `pip` and `buildout`!

👎 Incorrect code for this rule:

Use ```pip``` and ```buildout```!

# Marker character style

Use backtick characters ` for both blocks and inline code.

remark-lint: fenced-code-marker (opens new window)

👍 Correct code for this rule:

```js
import React, { PureComponent } from "react";
class Awesome extends PureComponent {
  // ...
}
export default Awesome;
```

👎 Incorrect code for this rule:

~~~js
import React, { PureComponent } from "react";
class Awesome extends PureComponent {
  // ...
}
export default Awesome;
~~~

# Use cases

Code blocks should be used for code snippets longer than a single line or terminal command quotations that contain sample output when the being executed.

Inline code spans on the other hand should be used to highlight e.g.

  • Executables - gcc, npm, go, python
  • Paths - /etc/hosts, src/main/java/com/arcticicestudio/icecore/hashids/Hashids.java
  • Version numbers - 0.2.0, 1.8.6-frost.2
  • Code for example reserved keywords, builtins and operators - this, true/false, String, =>
  • HTTP calls - GET, POST, PATCH

Don't use it for

Last Updated: 3/17/2021, 8:28:43 AM

← Comments →