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
⇣ Incorrect code for this rule:
import React, { PureComponent } from "react";
class Frost extends PureComponent {
// ...
}
export default Frost;⇡ Correct code for this rule:
```js
import React, { PureComponent } from "react";
class Frost extends PureComponent {
// ...
}
export default Frost;
```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
⇣ Incorrect code for this rule:
```
import React, { PureComponent } from "react";
class Frost extends PureComponent {
// ...
}
export default Frost;
```⇡ Correct code for this rule:
```js
import React, { PureComponent } from "react";
class Frost extends PureComponent {
// ...
}
export default Frost;
```Many command snippets are intended to be copied and pasted directly into e.g. a terminal. To protect the user to unintentional execute the copied code due to a newline (interpreted by the terminal as Enter) use a single backslash at the end of the line.
⇣ Incorrect code for this rule:
```sh
npx run docs:generate -- --template=winter --description="Sparkling and frozen" --elements="snow,frost,ice" --snowflakes=20
```⇡ Correct code for this rule:
```sh
npx run docs:generate -- --template=winter --description="Sparkling and frozen" \
--elements="snow,frost,ice" --snowflakes=20
```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 e.g. 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
⇣ Incorrect code for this rule:
```sh
$ echo "The winter is sparkling and frozen!"
```⇡ Correct code for this rule:
```sh
echo "The winter is sparkling and frozen!"
``````sh
winter="The winter is sparkling and frozen!"
echo $winter # The winter is sparkling and frozen!
```When using code blocks within lists make sure to use the correct indention to not break the list.
⇣ Incorrect code for this rule:
* Winter
```jsx
const Snow = <Snowflake amount=20 />;
```
* Frost⇡ Correct code for this rule:
- Winter
```jsx
const Snow = <Snowflake amount=20 />;
```
- FrostUse one (1) backtick character ` to create a inline code span which will render all wrapped content literally.
⇣ Incorrect code for this rule:
The winter has ```sparkling``` and frozen ```elements```!⇡ Correct code for this rule:
The winter has `sparkling` and frozen `elements`!To learn what content should be wrapped please read the use cases chapter.
Use backtick characters ` for both blocks and inline code.
remark-lint: fenced-code-marker
⇣ Incorrect code for this rule:
~~~js
import React, { PureComponent } from "react";
class Snow extends PureComponent {
// ...
}
export default Snow;
~~~⇡ Correct code for this rule:
```js
import React, { PureComponent } from "react";
class Snow extends PureComponent {
// ...
}
export default Snow;
```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 -
go,npm,gcc - paths -
pkg/internal/transport/http/http.go,/etc/hosts - version numbers -
0.2.0,1.8.6-beta.2 - code e.g. reserved keywords, builtins and operators -
this,true/false,String,=>
Don't use it for