h759bkyo4/Documentation
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

Style Guide: Markdown Code Blocks (#403)

Browse source 
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:
Panagiotis "Ivory" Vasilopoulos 2024-03-12 18:38:42 +00:00
parent 465aaaa107
commit b9a17086c9
1 changed files with 10 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

11
content/improving-documentation/style-guide.md
View file

@ -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: 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 ### Images and UI Descriptions
Screenshots and other images can heavily improve the quality of an article without much effort. 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. - 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 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. - When using images, always use an adequate amount of alt text.
- Use Markdown code blocks for code, configuration files and terminal output.
{% admonition "warning" %} {% admonition "warning" %}