Code
Key Point
💡 Rules for code and code blocks.
Blocks
Avoid indentation based code blocks, use fenced code blocks 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.
remark-lint: code-block-style
👍 Correct code for this rule:
```js
import React, { PureComponent } from "react";
class Frost extends PureComponent {
// ...
}
export default Frost;
```
👎 Incorrect code for this rule:
```js
import React, { PureComponent } from "react";
class Frost extends PureComponent {
// ...
}
export default Frost;
```
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
👍 Correct code for this rule:
```js
import React, { PureComponent } from "react";
class Frost extends PureComponent {
// ...
}
export default Frost;
```
👎 Incorrect code for this rule:
```
import React, { PureComponent } from "react";
class Frost extends PureComponent {
// ...
}
export default Frost;
```
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=winter --description="Sparkling and frozen" \
--elements="snow,frost,ice" --snowflakes=20
👎 Incorrect code for this rule:
npx run docs:generate -- --template=winter --description="Sparkling and frozen" --elements="snow,frost,ice" --snowflakes=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 whitespace.
remark-lint: no-shell-dollars
👍 Correct code for this rule:
echo "The winter is sparkling and frozen!"
winter="The winter is sparkling and frozen!"
echo $winter # The winter is sparkling and frozen!
👎 Incorrect code for this rule:
$ echo "The winter is sparkling and frozen!"
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:
- Winter
```jsx
const Snow = <Snowflake amount=20 />;
```
- Frost
👎 Incorrect code for this rule:
- Winter
```jsx
const Snow = <Snowflake amount=20 />;
```
- Frost
Inline
Use one (1) backtick character ` to create a inline code span which will render all wrapped content literally.
👍 Correct code for this rule:
The winter has `sparkling` and frozen `elements`!
👎 Incorrect code for this rule:
The winter has ```sparkling``` and frozen ```elements```!
Marker character style
Use backtick characters ` for both blocks and inline code.
remark-lint: fenced-code-marker
👍 Correct code for this rule:
```js
import React, { PureComponent } from "react";
class Snow extends PureComponent {
// ...
}
export default Snow;
```
👎 Incorrect code for this rule:
~~~js
import React, { PureComponent } from "react";
class Snow extends PureComponent {
// ...
}
export default Snow;
~~~
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,=>
Don't use it for