This document provides guidance for 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.
The guidance in this document is intended to:
This document is WIP.
Only use inline HTML when markdown cannot provide the same result, and even so try to avoid inline HTML except where absolutely unavoidable. 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.
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.
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.
Preferably format VQL code blocks with the VQL formatter, for consistency.
Try not to overuse them. Especially try not to have two or more of them together. Try to only use them when the reader’s attention need to be drawn to something specific.
Often the content in an admonition can be rewritten as part of the normal text body.
Use - not *. Just for consistency.
privilege indicator - this will depend on 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 for page links so that Hugo will do link checking automatically. For internal links that are broken, Hugo will fail to compile and let you know immediately.
Always try to add a summary. When using the children shortcode it defaults
to creating a summary if one is not defined, which means it grabs the first few
paragraphs from the page. Usually this “auto-summary” is unsightly so it’s
better to carefully craft one rather than relying on “auto”.
Tags are recommended. These help users find related content. Do not use meaningless tags such as “velociraptor” or “DFIR”.
Top level section headings should be level-3.
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 community support on forums like Discord.
For example:
###### Example
L6 headings also won’t appear in TOCs, so this prevents that from accidentally happening.
Don’t use a colon after the word Example, but use one if it’s a lead-in phrase such as “For example…:”
Avoid line breaks in links.
Bold all UI elements (buttons, tabs, menu names) to help users scan the page quickly.