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 https://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 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
Including links to man page is encouraged. These links should point to their man
https://docs.voidlinux.org, have their title section number in
parenthesis, and contain no formatting in their bodies. For example:
man(1), and not
Auto links (links with the same title as URL) should use the following notation:
They should not be formatted like this:
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.