Linode Writer’s Formatting Guide

Updated by Edward Angert

Contribute on GitHub

View Project | View File | Edit File

Submissions which adhere to the following formatting guidelines are more likely to be accepted than those which do not, so review this page carefully. If you have any questions, contact contribute@linode.com.

General Layout

Linode Guides & Tutorials are written in PHP Markdown Extra. Additional Linode-specific markdown formatting notes are given further below, and submissions should be an .md file.

Linode Guides & Tutorials store metadata and other information in a header at the top of every page. Use the template below for your own guide.

Author Submission
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
---
author:
  name: Linode Community
  email: docs@linode.com
description: 'Two to three sentences describing your guide.'
keywords: 'list,of,keywords,and key phrases'
license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)'
published: 'Weekday, Month 00st, 2015'
modified: Weekday, Month 00th, 2015
modified_by:
  name: Linode
title: 'Guide Title'
contributor:
  name: Your Name
  link: Github/Twitter Link
  external_resources:
- '[Link Title 1](http://www.example.com)'
- '[Link Title 2](http://www.example.net)'
---

*This is a Linode Community guide. [Write for us](/docs/contribute) and earn $250 per published guide.*
----

Introduction

Introductions should be concise; explain what the goal of the guide is and why. If you’re introducing new software to the system, include a brief description and link to its official website whenever possible.

Before You Begin

The Before You Begin section is a basic area of prerequisites a reader should know or have completed before proceeding further in your guide. Use the template below and edit as needed:

Author Submission
1
2
3
4
5
6
7
8
9
## Before You Begin

1.  Familiarize yourself with our [Getting Started](/docs/getting-started) guide and complete the steps for setting your Linode's hostname and timezone.

2.  This guide will use `sudo` wherever possible. Complete the sections of our [Securing Your Server](/docs/security/securing-your-server) to create a standard user account, harden SSH access and remove unnecessary network services. Do **not** follow the Configure a Firewall section yet--this guide includes firewall rules specifically for an OpenVPN server.

3.  Update your system.

        sudo apt-get update && sudo apt-get upgrade

Include a Note about Root or Non-Root users

Guides Written for a Non-Root User
1
2
3
{: .note}
>
> This guide is written for a non-root user. Commands that require elevated privileges are prefixed with `sudo`. If you’re not familiar with the `sudo` command, see the [Users and Groups](/docs/tools-reference/linux-users-and-groups) guide.
Guides Written for a Root User
1
2
{: .note}
> The steps in this guide require root privileges. Be sure to run the steps below as `root` or with the `sudo` prefix. For more information on privileges, see our [Users and Groups](/docs/tools-reference/linux-users-and-groups) guide.

Include a Note about Example Variables

If using example variables, like example IPs, which should be changed throughout the guide, declare them in this section. For example:

1
Replace each instance of `example.com` in this guide with your site's domain name.

Paragraph Structure

Guides should be split into cohesive sections which flow from one sequence of events to the next. Each section title should be styled with an H2 heading element, and each subsection with an H3 heading so that scanning the In This Guide left sidebar should give the reader an overview of what will be done in the guide. Capitalize each noun, adjective, verb and adverb in the article title, H2 and H3 headers.

Each subsection should be split into numbered steps as shown below.

For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
## Using MySQL

1.  Log in to MySQL as the root user:
        mysql -u root -p

2.  When prompted, enter the root password.

### Create a New MySQL User and Database

1.  In the example below, `testdb` is the name of the database, `testuser` is the user, and `password` is the user’s password.

        create database testdb;
        grant all on testdb.* to 'testuser' identified by 'password';

2.  Exit MySQL.

        exit

### Create a Sample Table

1.  Log back in as `testuser`:

        mysql -u testuser -p

The tab size is set to four, and only soft tabs should be used. This can be configured in the settings of most text editors.

Markdown Formatting

Abbreviations and Acronyms

Upon first mention of a new concept or software, use the full name or term, then note the abbreviation or acronym in parenthesis beside it. The abbreviation/acronym can then be used in the article from that point. For example: Lightweight Resource/Provider (LWRP).

Bold and Italics

Use a Bold font weight for buttons, menu selections and anything that requires emphasis or that you want to stand out to the reader. Italicize new terms and concepts the first time they are used.

Formatting Example
**bold** bold
*italics* italics

Commands

Commands that are not inline with paragraph text should be indented one tab from the beginning of the copy.

For example:

1
2
3
Update your system:

    yum update

Update your system:

1
yum update

Inline commands should be denoted by backtics.

Formatting Example
Update your system by running `yum update`. Update your system by running yum update.

Example IP Addresses

Example IPs should use the documentation address blocks given in IETF RFC 5737. These are:

  • 192.0.2.0/24
  • 198.51.100.0/24
  • 203.0.113.0/24

External Resources/More Information

If you wish to provide links to external sites for the user to review after going through your guide, do so using the external_resources field in the page header. This will appear as a text block with links at the bottom of the page.

More Information

You may wish to consult the following resources for additional information on this topic. While these are provided in the hope that they will be useful, please note that we cannot vouch for the accuracy or timeliness of externally hosted materials.

Files and File Excerpts

Use the file format when adding the content of a whole file to a guide. If only a part of the file is being shown, use the file excerpt format. Exceptionally long files should be shown in parts and have the whole file linked, if needed.

Within the file formatting, a code language or syntax should be defined at the end of the : ~~~ line to set how the text is displayed. A list of supported languages with examples can be found here.

Example: File format

Formatting Example
{: .file }
/path/to/file.html
:   ~~~ conf
    #Sample file text
    Sample file syntax
    ~~~

Example: File Excerpt format

Formatting Example
{: .file-excerpt }
/path/to/file.html
:   ~~~ ini
    #Sample file excerpt text
    Sample file excerpt syntax
    ~~~

File Paths

Inline file paths should be unformatted text.

Formatting Example
Navigate to `/var/www/html`. Navigate to /var/www/html.

Headings

Formatting Example
## Section title (h2) Section title (h2)
### Subsection (h3) Subsection (h3)

Images

Images should be in .png or .jpg format. If an image is over 650 pixels wide, include both the original and one which is scaled down to 650 px. Image filenames cannot contain spaces and should use hyphens (-) to separate words instead of underscores (_).

When adding an image, ensure that all identifying attributes such as names and IP addresses are removed, obfuscated, or replaced with dummy text, such as example_user or 192.0.2.0. Be mindful of metadata in images taken with mobile devices.

Up to 650 px wide. Over 650 px wide.
![description](/docs/assets/filename.png) [![description](/docs/assets/filename_small.png)](/docs/assets/filename.png)

Key Combinations

When instructing to use a combination of keys, format them in bold.

Formatting Example
Press **CTRL+N** then **X** to exit the program. Press CTRL+N then X to exit the program.

Internal links to other Linode guides should be relative, starting at /docs/, and external links should be formatted as shown below and use HTTPS URLs whenever possible.

Internal External
[Getting Started](/docs/getting-started) [Apache HTTP Server Documentation](https://httpd.apache.org/docs/)]

Lists

Be sure that lists have the proper horizontal spacing. This should be two spaces for ordered lists and three for unordered. This is to keep the lists aligned properly with the four-space soft tabs used in the guides.

Ordered Unordered
1  Step 1.

2  Step 2.

3  Step 3.
*   Item 1.

*   Item 2.

*   Item 3.

Notes and Cautions

Notes should be important text that does not necessarily fit the narrative of the preceeding step or paragraph. If a step in your guide can cause any major issues with the user’s Linode or computer, a caution note should be included.

Formatting Example
{: .note}
>
> This is a sample note.
{: .caution}
>
> This is a sample caution.

Numerical Values

1-10 Greater than 10
Use words (one, two, three, etc.) Use numerical digits (11, 22, 33).

Sentence Spacing

Use single spaces between sentences; do not double-space.

Tables

FormattingExample
{: .table .table-striped}
| Left-Aligned | Centered | Right-Aligned |
| ---------------- |:-------------:| -----------------:|
| Columns,     | both          | headers        |
| and              | line items, | are aligned   |
| by the hypens | and colons | above.     |

Variables

Variables that the reader will need to change for their system or preference should be formatted using backtics. Do not include any brackets or parentheses when using these temporary values in examples, as the reader may include them in their final version.

Formatting Example
Change the `password` and `username` values. Change the password and username values.

This guide is published under a CC BY-ND 4.0 license.