Keywords in upper case follow the meanings specified in RFC-2119.
Even though it's very unlikely, please search through the existing issues and look for existing similar ones before submitting your own.
Please try to group related changes into single pull requests and create additional ones if necessary. This will make reviewing and merging much easier and faster.
This project uses Markdown as its markup language.
Not all the files in this project follow these guidelines yet, as we established them after a large portion of this guide had been written already. If you find any style inconsistencies, please file a report or send a pull request to fix them.
When changing a file to use semantic linefeeds, please apply this in a separate commit and do not perform any other content changes in the same commit.
The markup parser is markdown-it,
which can be extended by plugins
and is furthermore accompanied
by some of Vitepress's custom extensions.
You can find the list of plugins we use
in the markdown
option
in docs/.vitepress/config.ts
.
Lines MUST NOT be longer than 80 characters, except for tables, urls and code blocks.
Split text using semantic linefeeds. Using those, you will hardly ever come near 80 characters on a single line. Even when you do, you should be able to add line breaks at fitting locations trivially. This file can serve as an example.
Blocks SHOULD be indented by 2 spaces, but visual indentation is preferred. Inline code should be using code fences, especially when syntax highlighting is desired.
Example:
- This sentence can be split
using a semantic linefeed,
as mentioned earlier.
1. The very same thing applies to this line,
but it uses a three-spaces indent instead.
1. You could also indent this block
by 4 spaces.
Trailing whitespace SHOULD be avoided.
Insert manual line breaks using <br>
tags
instead of using two trailing spaces.
Headings MUST be preceded by two blank lines, unless they directly follow another heading or the beginning of the file.
Enumeration and code blocks SHOULD be surrounded by blank lines.
Enumeration lists MUST begin on the same indentation level as their surrounding text.
-
Unnumbered lists SHOULD use the following hierarchy:
- first level * second level
-
Numbered lists SHOULD use
1.
for all items when possible:1. This is the first item, but it may change places in the future. 1. By always using ``1.``, we can swap lines around without worrying about numbering.
Hyperlinks SHOULD NOT be inlined and instead use deferred definitions. The linked text SHOULD NOT be "here". Instead, describe what the target page covers, represents, or can otherwise be summarized as and add the reference to the describing text. Use a descriptive shorthand if the linked text does not speak for itself.
Hyperlink definitions can be placed after a paragraph, at the end of the section, or at the end of the document – whatever seems more appropriate.
Example:
This is some normal text.
Information on "text"
can be found [on Wikipedia][wiki-text].
<!-- and not "here" -->
[wiki-text]: https://en.wikipedia.org/wiki/Text
For relative links,
follow the Vitepress recommendation
of referencing the files with their .md
extensions.
Use absolute paths when linking
between the guide and the reference sections.
If the relative URL is short,
you MAY directly specify the target URL in text.
The page's title is specified in YAML front matter and is inserted into the rendered as a heading of level one. Any subsequent headings of the file MUST NOT be of heading level two or lower (where lower refers to the significance, not the numeric value).
Each heading SHOULD be under a heading with one level higher.
Thus, the first markdown heading of the The following heading styles MUST be used in the displayed order for technical reasons (e.g. h3 must come after h2 or higher, and not after h1).
Example:
---
title: This will be heading 1
---
## Heading 2
### Heading 3
With text
### And proper spacing
## New Heading 2
### This SHOULD NOT be a h4
File paths (relative or absolute) MUST be specified like this:
`Packages/SomePackage/somefile.ext`
All paths MUST be written with forward slashes unless they are meant to be used in Windows.
File extensions (when referring to file types) MUST be written like this:
`.ext`
All key bindings SHOULD be written
using our custom Key component.
The Key chord in the k
property
uses the same formatting
as for Sublime Text keymaps.
You MAY use command
and option
for macOS-specific bindings.
<Key k="ctrl+t" /> <!-- single-chord -->
<Key k="ctrl+k, ctrl+k" /> <!-- multi-choord binding -->
<Key k="option+command+up" /> <!-- uses macOS-specific modifiers -->
Unless otherwise denoted, all key bindings MUST refer to the default for Windows.
-
Command captions in the command palette MUST be written as follows:
**Preferences: Settings - User**
-
Menu item captions (from the main menu by default) MUST be written as follows (notice the
→
):*Preferences → Package Settings → ...*
The following comment 'keywords' may be used at the beginning of a comment to mark a section for review:
- XXX
- TODO
Examples:
<!-- TODO add some screenshots -->