Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2024-12-27 08:19:24 -05:00
Code Issues Packages Projects Releases Wiki Activity

Improve code block Markdown guidelines (#749)

Browse Source
This commit is contained in:
Andrew David Wong 2018-12-02 17:16:59 -06:00
parent 3f25b1c8c9
commit 2bfd51e723
No known key found for this signature in database
GPG Key ID: 8CE137352A019A17
1 changed files with 20 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
basics_user/doc-guidelines.md
View File

@ -254,25 +254,33 @@ When making contributions, please try to observe the following style conventions
where appropriate.
* Use underline headings (`=====` and `-----`) if possible.
If this is not possible, use Atx-style headings on both the left and right sides (`### H3 ###`).
* When writing commands to be entered into a terminal:
* State in the text above the commands that the user shall open a terminal and run those commands.
E.g.
* When writing code blocks, use [syntax highlighting](https://github.github.com/gfm/#info-string) where [possible](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers) and use `[...]` for anything omitted.
* When providing command line examples:
* Tell the reader where to open a terminal (dom0 or a specific domU), and show the command along with its output (if any) in a code block, e.g.:
~~~markdown
Open a terminal in your AppVM and run
Open a terminal in dom0 and run:
```shell_session
$ cd test
$ echo Hello
Hello
```
~~~
* Precede each command with a non-empty prompt that fits the needs.
As a minimum, the prompt should contain a trailing `#` (for the user `root`) or `$` (for other users) on Linux systems and `>` on Windows systems, respectively.
* Put the expected output below the command as usual or use a separate code block for that.
You should write `[...]` for omitted parts of the output.
* Use [syntax highlighting](https://github.github.com/gfm/#info-string) where [possible](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers).
* When quoting (script) files:
* Use code blocks with [syntax highlighting](https://github.github.com/gfm/#info-string) where [possible](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers).
* You should write `[...]` for omitted parts.
* Precede each command with the appropriate command prompt:
At a minimum, the prompt should contain a trailing `#` (for the user `root`) or `$` (for other users) on Linux systems and `>` on Windows systems, respectively.
* Don't try to add comments inside the code block.
For example, *don't* do this:
~~~markdown
Open a terminal in dom0 and run:
```shell_session
# Navigate to the new directory
$ cd test
# Generate a greeting
$ echo Hello
Hello
```
~~~
The `#` symbol preceding each comment is ambiguous with a root command prompt.
Instead, put your comments *outside* of the code block in normal prose.
* Use `[reference-style][ref]` links.
`[ref]: https://daringfireball.net/projects/markdown/syntax#link`