Vultr DocsLatest Articles

Vultr Docs Creator Guide

MarkdownVultrTechnical Writing
MD
Updated on July 25, 2024
Vultr Docs Creator Guide header image

Introduction

Welcome to the Vultr Creator Program. We are excited to have you as a contributor to help expand our documentation library. The major purpose of the program is to offer our customers and the global developer community critical information that guides them when developing solutions on Vultr's Global Infrastructure.

Our primary purpose is to grant developers access to readily available documentation that is beneficial when creating solutions using Vultr Infrastructure. Whenever a developer thinks of a new idea, there should be an easy-to-follow resource that guides them on how to turn the idea or challenge into a production-ready solution.

To ensure that articles about Vultr products and services are of high quality and consistent to help developers achieve their goals, please read and follow this creator program guide to produce articles that meets the Vultr standards.

Prerequistes

Before following this guide, visit the:

How to Request an Assignment

  1. Log in to your account on the Vultr Creator Dashboard.
  2. Choose a title from the Available Topics, or navigate to the Doc Assignments, click Request Assignment, and suggest a new idea you think is a great addition to Vultr Docs.
  3. When your assignment is ready, the state changes from Requested to Allocated. If we add new suggestions, be sure to check the notes on your assignment before you begin.

For a complete guide on how to request your assignments, visit the Introduction to the Vultr Creator Dashboard guide.

How to Submit Your Assignment for Review

  1. Write your article in the Vultr-flavored Markdown format.
  2. Edit, and thoroughly Proofread your article. We don't accept articles that require extensive editing.
  3. Test your article by performing all steps yourself before submitting it for review. It's recommended to test your article steps on live Vultr Infrastructure.
  4. Navigate to Doc Assignments, click your assignment, scroll down, and use the submission wizard to submit it for review.
  5. We will review, validate your article, and send you a payment proposal if we approve your submission.
  6. If you accept the proposal, we will publish your article after verifying that you've been paid.

For more information on how to submit your articles and accept payment proposals, visit the Introduction to the Vultr Creator Dashboard guide.

Style Requirements

This section describes style elements you should follow when writing your articles. We follow the Chicago Manual of Style if an issue isn't addressed in this guide.

Write in the Second Person

Documentation is not a blog post. When writing your articles, you should use second-person pronouns, not first-person. The second person directly addresses a reader as you.

In your articles, use second person pronouns: you, your, and yours. Don't use first person singular pronouns: I, me, my, and mine.

  • Correct: You will deploy a server in New York.
  • Not correct: I will show you how to deploy a server in New York.

Be cautious with first-person plural pronouns like we, us, our, and ours. When used, they should only refer to Vultr.

  • Correct: Choose our New York data center to deploy the server.
  • Not correct: We will learn how to deploy a server in the New York data center.

If you must use the third person, avoid the gendered pronouns he, she, his, and hers. Instead, use they and their.

Use Active Voice

Strive to write in the active voice, and not the passive voice. When using the active voice, the sentence's subject, often the user, does the action. In passive voice, the sentence's subject is the recipient of the action. Words like was and by are clues that you're writing in the passive voice.

Active voice instructions are usually shorter and easier to understand. Passive voice is usually less engaging, wordy, and more complicated than active voice.

Exceptions to the Rule: When Passive Voice is Preferred

Although you should use active voice, there are some exceptions where passive voice is better. For example, when the system performs an action or the main subject is unknown, who, or, what is acting?

  • Active voice, but Improper: The developers scheduled the database to update weekly.
  • Passive voice, better phrasing: The database is updated weekly.

You can also use passive voice to avoid blaming the user directly for an error. For example:

  • Active voice, but not friendly: If the installation fails, you probably entered wrong information in the configuration file.
  • Passive voice, but friendlier: If the installation fails, wrong information probably was entered in the configuration file.

Use Task-focused Language

Try to use motivational language that embraces and focuses on the reader's outcome. Instead of explaining what the reader will learn, or benefit from your article, focus on what the reader will do if all steps are followed correctly.

For example, instead of: "Today, you'll learn how to install Kubernetes", try: "At the end of this article, you will have a working Kubernetes cluster."

Use Strong Action Statements

Avoid weak writing. Weak modifiers and superlatives such as quite, very, and extremely reduce your article quality. Avoid starting a sentence with weak verb constructions like There is, There are, and There were.

Use Present Tense

A reader performs your article tasks in their present, so the present tense is appropriate and more comfortable to read than the past or future tense.

  • Replace this: MySQL will prompt you for the password.
  • With: MySQL prompts you for the password.

If you must emphasize that something occurs later (from the reader's perspective), it's okay to use the future tense. For example: If MySQL prompted you for a password upon login, your database user is secure.

Use an Implied Subject

It's common to omit you in instructional steps when it's clear that the reader is the subject. An implied subject makes the article less repetitive.

  • Replace this: You need to edit the Apache control file.
  • With this: Edit the Apache control file.

In this case the subject you understands they must edit the file. However, you can use explicitly mention the subject when necessary, for example, in a troubleshooting section.

  • Direct: If the web server fails to listen on the custom-defined port, you need to edit the Apache control file and pre-define it.
  • Indirect: If the web server fails to listen on the custom-defined port, edit the Apache control file.

Use Consistent Terminology

Avoid multiple variations when referring to the same product, function, or UI elements. For example, don't ask the user to press Enter in one section, then press Return in another. This creates confusion and inconsistency in your article.

Product Name Capitalization

Research terms you are unsure of how to capitalize, such as WordPress versus Wordpress, PyTorch versus Pytorch. When starting a sentence with a product name, command, or trademark that usually is lowercase, Vultr follows the Wikipedia Manual of Style for Trademarks. Below are some examples to consider:

Examples of Correct Capitalization

  • Rsync transfers files and folders that have changed recently. You can copy your files with the rsync command.
  • Cron is a task scheduler. You can schedule tasks with cron to run at specific times.
  • iCloud is a cloud service. You can use iCloud to store your files.
  • ownCloud is a self-hosted filesharing application. You can use ownCloud to host and share files on your server.

Examples of Wrong Capitalization

  • rsync transfers files and folders that have changed recently. You can copy your files with the rsync command.
  • cron is a task scheduler. You can schedule tasks with cron to run at specific times.
  • ICloud is a cloud service. You can use iCloud to store your files.
  • OwnCloud is a self-hosted filesharing application. You can use owncloud to host and share files on your server

Avoid "Here" for Links

Avoid using here or click here when referencing other resources in your article. Instead, the link should describe itself to help the reader understand where it goes and improve search engine optimization (SEO). Avoid links like these:

[Click here](https://example.com/example-doc) to learn how to install a Marketplace app.

Download the latest version [here](https://www.example.com/download/).

Instead, write those links as:

Learn how to [install a Marketplace app](https://example.com/example-doc/).

Download the latest version [at the official Marketplace website](https://example.com/download/).

Descriptive links are friendlier for search engines and help the reader understand the link's context before clicking.

Slang, Jokes, Metaphors, and Hype

Please avoid advocacy and promotional hype in your documentation, as well as slang, jargon, jokes, idioms, metaphors, idioms, clichés, oxymorons, and euphemisms. Instead, focus on the facts, tasks, purpose, and code that benefits the user.

  • Avoid this: FoobarDB version 12 is armed to the teeth with amazing high-availability features that will exceptionally blow your mind.
  • Instead, say: FoobarDB version 12 supports high availability with hot standby and failover in case of failures.

Use English and US Spelling

  • Write your article in English.
  • Use the US spelling convention for words that vary by locale. For example:
    • Use license, not licence
    • Use synchronize, not synchronise
    • Use behavior, not behaviour
    • Use color, not colour
  • Avoid non-English words or phrases, such as de facto or ad hoc.
  • Avoid Latin abbreviations for common English phrases:
    • Use for example, not e.g.
    • Use that is, not i.e.
    • Use and so on, not etc. or et cetera

Date Formatting

Use a.m. or p.m. followed by a space. For example:

  • Correct: The server reboots at 11:52 a.m. each Tuesday.
  • Incorrect: The server reboots at 11:52 AM each Tuesday.

Redundant Date Phrasing

When using a.m. and p.m., avoid redundant phrases like in the morning. The abbreviations a.m. and p.m. always refer to a time before or after noon.

  • Avoid: The server reboots at 3:00 a.m. in the morning.

Midnight and noon

Don't use ambiguous constructions like 00:00 a.m. or 12:00 p.m. Instead, use midnight and noon.

  • Correct: The scheduler automatically clears the cache daily at noon.

24-Hour Time Formatting

If you find a.m. and p.m. problematic, use the 24-hour format in your article because it does not serve any repetitions in time. For example:

  • Correct: The scheduler automatically clears the cache daily at 12:00.

Punctuation

  • Avoid exclamation points! They are not appropriate for technical documentation.
  • Use one space after a period between sentences.
  • Because documentation must be unambiguous., use the Oxford (or serial) comma to avoid confusion.

Acronyms

Define acronyms before their first use. Leave a space between the definition and an acronym.

  • Correct: Deploy your Vultr Kubernetes Engine (VKE) cluster in the customer portal.
  • Incorrect: Deploy a Vultr Kubernetes Engine(VKE) cluster.

Steps in Narrative Form

Do not use first, next, finally, or lastly in a narrative form to describe a series of steps like this:

First, read the program guidelines.
Next, read the style guide.
Next, write an article.
Finally, submit the article to Vultr.

Also, don't use the adverb forms of steps like firstly, secondly, thirdly, or lastly.

Instead, use an ordered list to describe the steps like this:

1. Read the program guidelines.
1. Read the style guide.
1. Write an article.
1. Submit the article to Vultr.

> Vultr uses 1. as the list marker. This Markdown format allows you to move, add, and delete items without renumbering. However, to avoid confusion, you can correctly use an ordered list in its correct sequence as below:

1. Read the program guidelines.
2. Read the style guide.
3. Write an article.
4. Submit the article to Vultr.

Uncomparable Modifiers

Avoid modifiers like very, absolutely, and extremely to uncomparable terms like true, false, impossible, and unavoidable. Here are a few common examples you should avoid:

  • extremely unavoidable
  • absolutely false
  • very final
  • increasingly impossible

Complex Phrases

Vultr prefers plain language over complex phrases. For example:

  • Replace a number of with many
  • Replace all of a sudden with suddenly
  • Replace an adequate number of with enough
  • Replace because of the fact that with because
  • Replace carry out an evaluation of with evaluate

Screenshots and Images

Use an adequate number of images in your documentation. Verify that important steps have enough supporting images with proper text descriptions to offer assistive technology readers sufficient information about your image.

Images in your documentation provide visual clues and make your article more engaging. You must add alternative text that describes the image for accessibility and discovery in search engines.

Do not depend on images to display unexplained information. For example, don't use terminal screenshots to show command outputs, instead, copy and paste part of the command output as text in your article. For example:

Output:

   Version 13.0.2

If your article uses images, upload them to a public location and add the direct URL to your article. Strictly use JPG, PNG, or GIF file formats. When used correctly, your images should be visible in the submission preview wizard.

To insert images in your article, use the markdown syntax ![Alt Text](https://host/image.jpeg). For example:

Become a Vultr Creator

If you're unable to view your images in the submission wizard, verify that your image URL contains an image extension such as .png.

Example Network Addresses

When writing domain names, Server IP Addresses, or using networking examples, use the following permitted addresses.

Structure

Our articles are arranged into the following logical sections:

  • Title
  • Introduction
  • Prerequisites
  • Main content
  • Next Steps and References

Title

The article title is the only allowed H1-level heading (#), but don't include it in your article. When requesting an article from the Available Topics, verify that it states the goal of the article and key technology used. For example:

How to [Do a Task] with [Software Tools] on [Operating System]

When validating your submission, we may edit your title for SEO or other purposes.

The Introduction

The Introduction section sets the reader's expectations, motivates them to read the rest of the article, and summarizes what they will do. It's usually three paragraphs or less. When writing your introduction, keep these questions in mind:

  • What is the article about? Is it an installation guide, a reference guide, a quickstart, a description of an architectural pattern, or something else? What software will the reader use?
  • Why should the reader keep reading your article? What will they learn? What are the benefits to the reader?
  • What will the reader accomplish in the article? By the end of it, will they have set up a new server, built a production-ready application, secured their data, gained a new skill, or something else?

Organize your article by aligning your main content with the points made in the introduction. A strong introduction helps the reader understand what the main content is all about, and quickly decide if they should keep reading.

Focus on the article's solution instead of the reader or the technology. Don't use phrases like "you will learn how to," which place the focus on the reader. Instead, use phrases like "you will install," or "you will set up".

For example, if your article is about building an application in Go, keep the introduction's focus on the application and the solutions it provides instead of explaining the history of the Go programming language.

Prerequisites

The prerequisites section is where you explain all requirements the reader should consider before following the steps in your article. You should include information like:

  • The type and number of servers to deploy, distribution, specifications, and network requirements.
  • Connection methods such as SSH, Telnet, SFTP, or Kubectl.
  • Common software stacks to deploy such as LAMP, LEMP, or MERN.
  • DNS settings
  • Local workstation configuration or software requirements
  • Accounts required on other services like social media or other remote APIs
  • Links to conceptual articles or background articles that will assist the reader
  • Required skills if your article requires the reader to have a specific skill.

This section should be formatted as a list of steps for the reader to follow. Each step should link to an existing article that explains the steps required to complete that point. If instruct the reader to "Install a LAMP server," link to a Vultr reference article that explains how to install the stack.

Be specific. Telling the reader they "should be familiar with SQL" without a reference link isn't helpful. Instead, spell out the specifics and link to a resource for more information. For example, "You should be familiar with MySQL views and stored procedures. Get started by building your skills."

Visit the Vultr list of reference articles later in this guide.

If no reference article exists for a prerequisite step, please request an assignment to write one. You can also link to the upstream product documentation.

By linking to existing documentation for prerequisite steps, you are assured that the content is correct and maintainable. If the procedure for a prerequisite step changes, Vultr updates the reference article instead of updating many individual articles with the steps.

Main Content

The article's main content explains all steps that a reader needs to follow and why they need to in a particular way. Every major section should begin with an H2 (##) heading. Child sections can use the H3 (###) or H4 (####) headings.

Terminal Commands

Each command a reader must run in the terminal should be in a separate code block.

  • Before each command block, explain what the command does.
  • After the code block, explain in detail what the command achieves. For example, what the arguments do and why the reader should use them.
  • If the command output is important to show, use a separate code block.

Here's an example in Markdown of how a command and its output should appear in Vultr documentation.

Run the following command to display a list of IP addresses for `www.example.com`.

    $ dig +short www.example.com

The `+short` parameter instructs `dig` to display nothing except the short form of the answer.

Output:

    192.0.2.100
    192.0.2.101
    192.0.2.102

If the reader needs to be in a specific directory or change to a new one, indicate the step before running any additional commands.

When editing a file, introduce it by describing its purpose, then explain what changes the reader will make. This helps the reader when they need to customize, update, or troubleshoot issues in your article.

Explicitly tell the reader to create or open a file in a text editor. We prefer nano for documentation if it's available, otherwise, use vi since it's the default editor for UNIX systems.

Transitions

Every major step should briefly introduce what the reader will do, and have a closing summary describing what they did, and what's required next. Transitions give the reader context to help them follow the article.

Next Steps and Reference

Instead of a Conclusion section that merely summarizes what the reader accomplished by following your article. Use the opportunity to suggest the next steps and provide links to reference material such as related Vultr documentation.

Edit Your Article

Great technical writing requires great writing, not just solid technical knowledge. Your article might have all the needed technical information, but if it's poorly organized and sloppily written, it's not useful to the reader.

  • Always proofread and edit your article before submitting it to Vultr for review.
  • Follow the standard rules of English grammar and punctuation.
  • Use the standard format described in this style guide.

Many authors use the following tools to review articles before submitting them to Vultr Docs:

These are helpful, but none of them is a substitute for a human editor. We recommend using resources like the ones below to enhance your technical writing skills.

Resources

Technical Writing Resources

Depending on your writing environment, we recommend the following tools:

  • Markdown Editors: Visual Studio Code, Mark Text, Typora, Sublime Text
  • Word Processing: Libre Office
  • Validation: Vultr MDTK, Grammarly

Plain Language Resources

If you'd like to learn more about plain language, visit the following resources:

Plain Language Examples

Below are three examples of the same information, written in different styles.

  • Example 1 is too wordy.
  • Example 2 is too brief.
  • Example 3 is in plain language, which we prefer.

Please compare these examples to see the differences:

Example 1: Content is too Wordy

This version is too wordy. It forces the reader to pick out the critical information from the surrounding unimportant details. They might be interesting details but don't help the reader perform the intended task.

The first thing you need to do is open a terminal on your machine. After you open the terminal, use the SSH command to connect to your server. Make sure you don't connect as the "root" user because that's dangerous. Instead, you should use your username. It will take a few seconds. Now, when you are connected, type these commands. I'll explain what they do in a minute.

   $ sudo snap install --classic certbot

The first part of the command is the sudo command elevates your privileges, It is just a fancy way to say "make more powerful." The snap command is a snap package manager. It's a package manager that installs and manages snap packages. The --classic flag tells snap to install the snap package in the classic mode, which means you aren't using strict confinement.

The certbot command is a snap package that installs and manages the Let's Encrypt certificate. You'll use that later in the article. Certbot is a free, open-source software tool for automatically using Let's Encrypt certificates on manually-administrated websites to enable HTTPS. Certbot is made by the Electronic Frontier Foundation (EFF), a 501(c)3 nonprofit based in San Francisco, CA, that defends digital privacy, free speech, and innovation.

Example 2: Content is too Brief

This version is too brief. It leaves out important information and doesn't explain what the command does.

Connect to the server and run:

   $ sudo snap install --classic certbot

Example 3: Content is Plan Language (preferred)

This version is in plain language. It has all the necessary information and does not overload the reader with unimportant details.

  1. Connect to your server with SSH as a non-root user.

        $ ssh myuser@exampleserver

  2. Install Certbot with Snap. Certbot requires you to use the --classic flag to install with Snap.

        $ sudo snap install --classic certbot

Strive to use plain language in all your documentation.

Reference Articles

Many Vultr Docs articles have similar prerequisite steps and repeating these details in every article creates duplicate content and maintenance difficulties. For example, a typical LAMP based installation guide usually has several steps before the actual software installation, such as:

  • Update the server
  • Create a new user with sudo access
  • Install Apache
  • Install PHP
  • Install MySQL

Link to our reference guides instead of repeating the details in your article's prerequisite section. For example:

If a prerequisite step in your article is common, please search the Vultr Docs library and link to an existing reference guide. For your convenience, below are some of our most popular guides.

Core Content Categories

System Administration

Firewall

Networking

SSL / TLS / Let's Encrypt / Certbot

Software Stacks

Troubleshooting

Vultr-Flavored Markdown

Use the Vultr-flavored Markdown when writing for Vultr Docs. Vultr-flavored Markdown is Vultr's in-house, non-standard Markdown format. Please pay special attention to code blocks and keystroke symbols. The main differences between Vultr-flavored Markdown and other common Markdown flavors are:

  • Vultr Markdown does not allow inline HTML. You can only use plain text with Markdown formatting.
  • Vultr uses a special syntax to represent keystrokes, which is explained later in this article.
  • Fenced code blocks are not supported.
  • Code blocks do not support highlighting or line numbers.

For the best results, please follow the tips below. To check your formatting, please use the preview tab in the Vultr Creator Dashboard when submitting your assignment.

Paragraphs and Line Breaks

Example:

A paragraph is simply one or more consecutive lines of text separated by blank lines. Normal paragraphs should not be indented with spaces or tabs.

Add a blank line to start a new paragraph.

Result:

A paragraph is simply one or more consecutive lines of text separated by blank lines. Normal paragraphs should not be indented with spaces or tabs.

Add a blank line to start a new paragraph.

Headers

Vultr automatically adds your article title as an H1 heading when publishing. Do not include the H1 (#) heading in your article, instead use the following headings:

## This is an H2
### This is an H3
#### This is an H4
##### This is an H5
###### This is an H6

Blockquotes

Example:

> This is a **blockquote** with two paragraphs. Lorem ipsum dolor sit amet,
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
>
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
> id sem consectetuer libero luctus adipiscing.

Result:

This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

Nested blockquote

Example:

> This is the first level of quoting.
> 
>> This is nested blockquote.
> 
> Return to the first level blockquote.

Result:

This is the first level of quoting.

This is nested blockquote.

Return to the first level blockquote.

Ordered lists

If the reader must perform steps in a particular sequence, use an ordered list. Vultr uses 1. as the list marker. This format allows you to move, add, and delete items without renumbering. The Markdown engine increments the numbers for you when previewing the article.

1. Read the program guide.
1. Read the style guide.
1. Request an assignment.
1. Write the article.

Result:

  1. Read the program guide.
  2. Read the style guide.
  3. Request an assignment.
  4. Write the article.

To avoid any confusion when writing your article, you can also use ordered lists in the correct sequence.

Example:

1. Read the program guide.
2. Read the style guide.
3. Request an assignment.
4. Write the article.

Result:

  1. Read the program guide.
  2. Read the style guide.
  3. Request an assignment.
  4. Write the article.

Ordered lists with 2 paragraphs

Example:

1. This is a list item with two paragraphs. Indent the second paragraph by 4 spaces to align with the list.

    Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. Donec sit amet nisl. Aliquam semper ipsum sit amet velit.

1. This is the second list item.

Result:

  1. This is a list item with two paragraphs. Indent the second paragraph by 4 spaces to align with the list.

    Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. Donec sit amet nisl. Aliquam semper ipsum sit amet velit.

  2. This is the second list item.

Unordered Lists

When presenting a list where the sequence doesn't matter, use an unordered list. Vultr prefers asterisks (*) as the list marker instead of hyphens(-). The order you list these steps does not matter.

Example:

Please gather the following items:

* Bread
* Apples
* Very small rocks
* Lead
* A duck

Result:

Please gather the following items:

  • Bread
  • Apples
  • Very small rocks
  • Lead
  • A duck

Code Blocks

Code blocks are indented with 4 spaces at the beginning of each line.

  • Use four spaces to create a code block.
  • Do not use triple backticks for fenced code blocks.
  • Do not use single backticks.
  • Do not use tabs.

Example:

<- Beginning of line

    int main() {
        std::cout << "Hello World!";
        return 0;
    }
  • Code blocks inside ordered or unordered lists are indented by eight spaces at the beginning of each line.
  • Text indented by four spaces becomes part of the list item.

Example:

1. This is item one.

    Here is the code for item one.

        int main() {
            std::cout << "Hello World!";
            return 0;
        }

2. This is item two.
3. This is item three.

Result:

  1. This is item one.

    Here is the code for item one:

     int main() {
     std::cout << "Hello World!";
     return 0;
 }

  2. This is item two.

  3. This is item three.

Inline Code

Use backticks for inline code as below:

`this is inline code`

Use inline code sparingly because it makes the text harder to read and follow. Use bold or italic text unless you describe a literal command or filename. Use a code block when possible instead of inline code.

Example:

Use the `printf()` function.

Result:

Use the printf() function.

Literal backticks

Wrap a command with two backticks if you need to show a literal backtick.

Example:

There is a "literal backtick (`) "here.

Result:

There is a "literal backtick (`) "here.

We support inline links.

Example:

This [example inline link](http://example.com/ "The Link Title") is titled "The Link Title".
[This link](http://example.net/) has no title attribute.

Result:

This example inline link is titled "The Link Title". This link has no title attribute.

Please do not use reference-style links like the example below:

Some popular search engines are [Google][1], [Yahoo][2], and [MSN][3].

[1]: http://google.com/ "Google"
[2]: http://search.yahoo.com/ "Yahoo Search"
[3]: http://search.msn.com/ "MSN Search"

Wrap URLs with angle brackets to make an automatic link.

Example:

Make automatic links: <http://example.com/> and <address@example.com>

Result:

Make automatic links: http://example.com/ and address@example.com

Emphasis

  • Use single underscores to make italic text.

    Use single underscores to make italic text.

  • Use double asterisks to make bold text.

    Use double asterisks to make bold text.

Underscores

It's common to have variable names in technical documents with underscores. Be careful to escape your underscores to prevent unexpected italics.

Correct:

THE\_EXAMPLE\_VARIABLE

THE_EXAMPLE_VARIABLE

Incorrect:

THE_EXAMPLE_VARIABLE

THE_EXAMPLE_VARIABLE

Special Characters

Use a backslash to escape special characters.

Example:

\*this text is surrounded by literal asterisks\*
\\
\`
\*
\_
\{\}
\[\]
\(\)
\#
\+
\-
\.
\!

Result:

*this text is surrounded by literal asterisks*
\
`
*
_
{}
[]
()
#
+
-
.
!

Keystrokes

Represent literal keystrokes with Vultr's shortcodes. Distinguish uppercase/lowercase with the shift key.

:key_x: is a lowercase "x".
:key_shift:+:key_x: is an uppercase "X".

X is a lowercase "x".
Shift+X is an uppercase "X".

Example Usage

Save the file by pressing :key_ctrl:+:key_x:, then :key_y:.

Result:

Save the file by pressing Ctrl+X, then Y.

Alphabet

:key_a: :key_b: :key_c: :key_d: :key_e: :key_f: :key_g:
:key_h: :key_i: :key_j: :key_k: :key_l: :key_m: :key_n:
:key_o: :key_p: :key_q: :key_r: :key_s: :key_t: :key_u:
:key_v: :key_w: :key_x: :key_y: :key_z:

Result:
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Numbers

:key_1: :key_2: :key_3: :key_4: :key_5:
:key_6: :key_7: :key_8: :key_9: :key_0:

Result:
1 2 3 4 5 6 7 8 9 0

Function Keys

:key_f1: :key_f2: :key_f3: :key_f4: :key_f5: :key_f6:
:key_f7: :key_f8: :key_f9: :key_f10: :key_f11: :key_f12:

Result:
F1 F2 F3 F4 F5 F6
F7 F8 F9 F10 F11 F12

Symbols

:key_tilde: :key_grave: :key_exclamation: :key_at: :key_pound:
:key_dollar: :key_percent: :key_carat: :key_ampersand: :key_asterisk:
:key_lparen: :key_rparen: :key_dash: :key_underscore: :key_plus:
:key_equals: :key_lbracket: :key_lbrace: :key_rbracket: :key_rbrace:
:key_pipe: :key_backslash: :key_semicolon: :key_colon: :key_quote:
:key_apostrophe: :key_lt: :key_comma: :key_gt: :key_period:
:key_question: :key_forwardslash: :key_space: :key_spacebar:

Result:
Tilde Grave Exclamation At Pound Dollar Percent Carat Ampersand Asterisk
Lparen Rparen Dash Underscore Plus
Equals Lbracket Lbrace Rbracket Rbrace
Pipe Backslash Semicolon Colon Quote
Apostrophe Lt Comma Gt Period
Question Forwardslash Space Spacebar

Special Keys

:key_esc: :key_backspace: :key_tab: :key_caps: :key_capslock:
:key_enter: :key_return: :key_shift: :key_control: :key_ctrl:
:key_super: :key_win: :key_command: :key_alt: :key_meta:
:key_printscreen: :key_sysrq: :key_scrolllock: :key_pause: :key_break:
:key_delete: :key_end: :key_pagedown: :key_pgdn: :key_insert:
:key_home: :key_pageup: :key_pgup: :key_up: :key_left: :key_down:
:key_right: :key_numlock:

Result:
Esc Backspace Tab Caps Capslock
Enter Return Shift Control Ctrl
Super Win Command Alt Meta
Printscreen Sysrq Scrolllock Pause Break
Delete End Pagedown Pgdn Insert
Home Pageup Pgup Up Left Down
Right Numlock

Tables

Do not use tables. The Vultr-flavored Markdown does not support tables of any kind.

Command Lines

Command lines should begin with a prompt. This makes it easier to identify the command line and its arguments. It also prevents the reader from accidentally copying the entire line and submitting it as a command without reviewing or editing it.

  • Linux root examples use a hash prompt #.
  • Linux standard examples use a dollar sign $.
  • PowerShell and Windows CMD examples should use the appropriate prompts PS> or C:\>.
  • Databases and application shells should use appropriate prompts.

For example:

A root user performing ls on Linux:

# ls

A standard user performing ls on Linux:

$ ls

A PowerShell user:

PS> ls

A CMD user:

C:\> dir

A MySQL user

mysql >

Thank You

Thank you for contributing to the Vultr Creator Program. If you find an error in our documentation, please click the Suggest an update button included in every Vultr Doc and suggest any improvements. If you have any questions about Vultr Creator Program or your content assignments, please raise a support ticket on the Vultr Creator Dashboard.