Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2024-10-01 01:25:40 -04:00
Code Issues Packages Projects Releases Wiki Activity

Update Markdown Conventions

Browse Source 
- Add convention for using relative rather than absolute paths
 - Follow the convention to insert a newline at the end of each sentence
 - Note the class of exceptions to the aforementioned convention
This commit is contained in:
Andrew David Wong 2018-02-03 15:08:05 -06:00
parent bddcd0cad2
commit 0c29e05f3d
No known key found for this signature in database
GPG Key ID: 8CE137352A019A17
1 changed files with 18 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
basics_user/doc-guidelines.md
View File

@ -146,25 +146,25 @@ Style Guidelines
Markdown Conventions Markdown Conventions
-------------------- --------------------
All the documentation is written in Markdown for maximum accessibility. When All the documentation is written in Markdown for maximum accessibility.
making contributions, please try to observe the following style conventions: When making contributions, please try to observe the following style conventions:
* Use spaces instead of tabs. * Use spaces instead of tabs.
* Insert a newline at the end of each sentence. * In order to enable offline browsing, use relative paths (e.g., `/doc/doc-guidelines/` instead of `https://www.qubes-os.org/doc/doc-guidelines/`, except when the source text will be reproduced outside of the Qubes website repo.
* Rationale: This practice is most appropriate for source that consists Examples of exceptions:
primarily of natural language text. It results in the most useful diffs * [QSBs] (intended to be read as plain text)
and facilitates translation into other languages while mostly preserving * [News] posts (plain text is reproduced on the [mailing lists])
source readability. * URLs that appear inside code blocks (e.g., in comments and document templates)
* If appropriate, make numerals in numbered lists match between Markdown * Files like `README.md` and `CONTRIBUTING.md`
source and HTML output. * Insert a newline at the end of each sentence, except when the text will be reproduced outside of the Qubes website repo (see previous item for examples).
* Rationale: In the event that a user is required to read the Markdown source * Rationale: This practice is most appropriate for source that consists primarily of natural language text.
directly, this will make it easier to follow, e.g., numbered steps in a set It results in the most useful diffs and facilitates translation into other languages while mostly preserving source readability.
of instructions. * If appropriate, make numerals in numbered lists match between Markdown source and HTML output.
* Rationale: In the event that a user is required to read the Markdown source directly, this will make it easier to follow, e.g., numbered steps in a set of instructions.
* Use hanging indentations * Use hanging indentations
where appropriate. where appropriate.
* Use underline headings (`=====` and `-----`) if possible. If this is not * Use underline headings (`=====` and `-----`) if possible.
possible, use Atx-style headings on both the left and right sides If this is not possible, use Atx-style headings on both the left and right sides (`### H3 ###`).
(`### H3 ###`).
* Use `[reference-style][ref]` links. * Use `[reference-style][ref]` links.
`[ref]: https://daringfireball.net/projects/markdown/syntax#link` `[ref]: https://daringfireball.net/projects/markdown/syntax#link`
@ -188,5 +188,8 @@ Please try to write good commit messages, according to the
[gh-pull]: https://help.github.com/articles/using-pull-requests/ [gh-pull]: https://help.github.com/articles/using-pull-requests/
[GitHub]: https://github.com/ [GitHub]: https://github.com/
[mailing lists]: /mailing-lists/ [mailing lists]: /mailing-lists/
[QSBs]: /security/bulletins/
[News]: /news/
[md]: https://daringfireball.net/projects/markdown/ [md]: https://daringfireball.net/projects/markdown/
[git-commit]: /doc/coding-style/#commit-message-guidelines [git-commit]: /doc/coding-style/#commit-message-guidelines