Although there will always be cases where command listings are appropriate, the contents of the Handbook should be written in American English (or the relevant language in the case of translations of the Handbook).
Outside of the 'installation' sections, step-by-step instructions containing 'magic' commands for copying-and-pasting are strongly discouraged. Users are expected to read the canonical documentation (e.g. man pages) for individual programs to understand how to use them, rather than relying on copying-and-pasting.
Command code-blocks should not be used to describe routine tasks documented
elsewhere in this Handbook. For example, when writing documentation for the
foo package, do not provide a command code-block stating that one should
install it via
xbps-install foo. Similarly, do not provide code blocks
describing how to enable the
For markdown formatting, the
void-docs project uses the
Versioned Markdown format, and enforces use
of the auto-formatter
vmdfmt, which works very similarly to
valid markdown is accepted by the formatter. The output format is described in
the project's README.
Void provides the package
vmdfmt. Otherwise you may
go get from the repo:
$ go get github.com/bobertlo/vmd/cmd/vmdfmt
To format a file you have edited, run:
vmdfmt -w <filepath>
To format the entire mdbook from the repository root, outputting a list of files modified, run:
vmdfmt -w -l <filepath>
Command code-blocks should start with a
$ character, indicating whether
the command should be run as
root or a regular user, respectively.
# vi /etc/fstab
$ sudo vi /etc/fstab
and also not:
Command code-blocks should be introduced with a colon (':'), i.e.:
$ ls -l
Placeholders indicate where the user should substitute the appropriate
information. They should use angle brackets (
>) and contain only
lower-case text, with words separated by underscores. For example:
# ln -s /etc/sv/<service_name> /var/service/
# ln -s /etc/sv/[SERVICENAME] /var/service/
Link text should not include sentence-level punctuation. For example:
[Visit this site](https://example.org).
[Visit this site.](https://example.org)
Links to other sections of the Handbook must be relative. For example:
When referring literally to a Handbook section, the section title should be placed in double-quotes. Otherwise, double-quotes are not required. For example:
For more information, please read the "[Power Management](./power-management.md)" section.
Void provides facilities to assist with [power management](./power-management.md).
The first reference to a command or man page must be a link to the relevant man
Auto links (links with the same title as URL) should use the following notation:
They should not be formatted like this:
If you're including new links (either internal or external) in the docs or
changing the current file structure, you should install
which can be obtained from the Void repos or by using
cargo. You can then
build the mdBook locally, which will run a linkcheck as well, or run it in
$ mdbook-linkcheck -s
This way, linkcheck will verify all the references, and warn you if there are
any issues. If any link you're using is correct but generating errors for some
reason, you can add its domain to the exclude list in
book.toml, under the
Filenames and directories should use kebab
case when splitting words. For
example the filename should be
Words that are part of trademarks or well known package names are exempt from
this rule. Examples include
NetworkManager which are well
known by their squashed names.
Prefer the active imperative voice when writing documentation. Consider the following examples:
Now we need to install the CUPS drivers and configure them.
This version is conversational and friendlier, but contains unnecessary language that may not be as clear to an ESL reader.
Install and configure the CUPS drivers, then configure them as shown.
This version contains a clear command to act, and a follow up that shows what will be done next. It is clear both to native English speakers, ESL readers, and to translators.
Notes should only be used sparingly, and for non-critical information. They
should begin with "Note: ", and not be block-quoted with
>. For example, the
Markdown should look like:
Note: You can also use program X for this purpose.
> You can also use program X for this purpose.
Block quotes (i.e.
>) should only be used to quote text from an external