This document provides guidance for the writing style in the Velociraptor documentation. It specifies some informal standards and advice with the goal of ensuring as much consistency as possible in our prose content irrespective of author.
The guidance in this document is intended to:
The advice is intended to be helpful and should not be seen as a hurdle to contributions. If your contribution doesn’t subscribe to all the guidelines that’s perfectly OK - we can fix it up to be more compliant during future reviews.
This document is a also work-in-progress, and not set-in-stone “rules”.
Our docs website is compiled by Hugo which interprets markdown based on the Commonmark standard. Therefore it’s best to avoid using features from any other flavors of markdown such as GFM, as they may not be rendered correctly or at all by Hugo.
Hard wrap paragraph text at 70 or 80 characters. This makes it easier to review GitHub pull requests, which display changes side-by-side in two columns.
Your code editor may provide an auto-wrap option or an extension that makes this easy. For example, in VSCode you can use Rewrap.
Exceptions to hard-wrapping are:
Only use inline HTML when markdown cannot provide the same result, and even so try to avoid inline HTML except when it’s absolutely necessary. Having as much content as possible in markdown form simplifies website style changes, as well as automated style checking and content updates.
When writing content in HTML the same style rules apply as described in the Markdown Content section.
We try not to overuse inline code or else the prose starts to look
like patchwork.
Use inline code only for:
Do not use it for:
For the last 2 cases above it is recommended to use bold text for emphasis the first time a term is used. When doing so it is not necessary to use quotes around the term.
We currently support browser, python, yaml, sql, json,
bash, powershell, vql, text, shell syntax highlighting via
the highlight.js highlighter.
Preferably format VQL code blocks with the VQL formatter, rather than SQL, although they are similar.
```vql
SELECT read_file(path="C:/Windows/notepad.exe", accessor="file")
FROM scope()
```
produces this syntax-highlighted code block
SELECT read_file(path="C:/Windows/notepad.exe", accessor="file")
FROM scope()
Try not to overuse admonition blocks. In particular, try not to avoid having two or more of them adjacent, especially if they are the same admonition type.
Try to use them sparingly when the reader’s attention needs to be drawn to something specific. Often the content in an admonition block can be rewritten as part of the normal text content, and therefore doesn’t need to be wrapped in it’s own block.
Currently we support 4 admonition types: note, tip, info,
warning.
Admonition titles are optional but recommended.
Use - not *. Just for consistency.
privilege indicator - this will depend on potential future changes to styling. TBD
use generic file names. omit version numbers and arch.
use platform alternatives where applicable
When providing command examples we should use a consistent order for
the command components: [binary] [command] [subcommand]
[flags] [args]
Use markdown links rather than Hugo ref or relref shortcodes.
Avoid splitting links across lines. Even though this is valid it makes future link maintenance more complicated. If a link is long:
Hugo will do internal link checking automatically. So always check your Hugo output for issues before submitting a PR.
When internal links are invalid, Hugo will fail to compile and refuse to start, but this only happens on dev server start, so do also remember to check the console output.
Always try to add a meaningful summary field to the page metadata.
When using the children shortcode, it defaults to creating a summary
if one is not defined, and it does this by grabbing the first few
paragraphs/sentences from the page which is often not ideal. Usually
this “auto-summary” is not very helpful so it’s better to carefully
craft one rather than relying on “auto-summary” feature.
Tags are recommended on KB articles. These help users find related content.
Do not use meaningless tags such as “velociraptor” or “DFIR”.
Avoid using tags that are terms which already appear in the page content, because those can just be found with regular index-based searches. A tag should ideally be an association with some broader concept that is not explicitly mentioned in the content itself.
vql.yaml)Top level section headings should be level-3/H3 (###). The reason
for this is that when presented on the website, H1 is already used for
the page title, and H2 is used for the name of each
function/plugin/accessor. So headings within the section for each
function/plugin/accessor need to be H3 or lower.
Examples should always use Level-6 headings, regardless of their position in the heading hierarchy. This ensures a consistent style for all examples and allows Hugo to create a hyperlink for each example, which is important for sharing on community support on forums like Discord.
For example:
###### Example
L6 headings also won’t appear in TOCs, so this also prevents that from accidentally happening.
Don’t use a colon after the word Example unless there’s a subsequent example title such as “Example: Recursive use case”.
Avoid line breaks in links.
Bold all UI elements (buttons, tabs, menu names) to help users scan the page quickly.