Style Guide: Markdown Code Blocks (#403)
Fixes #401. Refs: https://codeberg.org/Codeberg/Documentation/issues/401 Reviewed-on: https://codeberg.org/Codeberg/Documentation/pulls/403 Reviewed-by: Leo Heitmann Ruiz <eo@noreply.codeberg.org>
This commit is contained in:
parent
465aaaa107
commit
b9a17086c9
|
@ -41,6 +41,16 @@ Feel free to suggest any additional points and/or sections you deem necessary.
|
|||
|
||||
Follow these guidelines to organize the structure of your document:
|
||||
|
||||
### Code Blocks
|
||||
|
||||
- **Configuration files:** Small configuration files should be enclosed in Markdown code blocks.
|
||||
- **Command line input:**
|
||||
- If you include a command that is meant to be executed by an ordinary user, prepend the character `$`.
|
||||
- Likewise, if a command is meant to be executed by `root` / an administrator, prepend the character `#`.
|
||||
- **Command line output:**
|
||||
- If the output is of direct relevance to the user, avoid screenshots. Use a Markdown code block instead.
|
||||
- If the output is too large, try trimming irrelevant lines first and explain what the reader should look out for.
|
||||
|
||||
### Images and UI Descriptions
|
||||
|
||||
Screenshots and other images can heavily improve the quality of an article without much effort.
|
||||
|
@ -58,7 +68,6 @@ Before including screenshots, we highly recommend writing articles in text first
|
|||
- Use text to describe instructions (i.e. where does the reader need to click). Do not exclusively rely on visual cues (i.e. arrows, icons) in screenshots.
|
||||
- When possible, use text to describe what you expect the reader to see after following an instruction or a set of instructions.
|
||||
- When using images, always use an adequate amount of alt text.
|
||||
- Use Markdown code blocks for code, configuration files and terminal output.
|
||||
|
||||
{% admonition "warning" %}
|
||||
|
||||
|
|
Loading…
Reference in a new issue