Linode Writer's Formatting Guide

This guide provides templates and guidelines to use when creating or updating a guide for Linode Docs.

Updates, improvements, and bug fixes to Linode documentation are always welcome through GitHub via pull requests (PRs) or issues.

Through our Write For Linode program, authors can contribute new guides and be paid for their work. We ask that interested authors apply to the program with one or more writing samples so that we can evaluate your work. To learn more about the program and to complete an application, please visit our Write For Linode program page.

Linode Guides & Tutorials are written in Markdown. Our documentation site uses Hugo, a static site generator. Hugo-specific Markdown formatting notes are given further below.

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

File: Author Submission

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

--- author: name: Linode Community email: docs@linode.com description: 'Two to three sentences describing the purpose of the guide.' keywords: ["list", "of", "keywords", "and key phrases"] license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' published: 2017-11-29 modified_by: name: Linode title: 'Guide Title' contributor: name: Your Name link: Github/Twitter/LinkedIn URL external_resources: - '[Link Title 1](http://www.example.com)' - '[Link Title 2](http://www.example.net)' ---

If you’re updating an existing guide in our repository, you may also notice a deprecated field in the header. This defaults to false, and setting it to true inserts a pre-written message near the beginning stating that the guide is no longer maintained. Typically, this will be used on guides specific to applications or distributions that have reached End of Life (EOL).

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.

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

File: Author Submission

1 2 3 4 5

## Before You Begin 1. If you have not already done so, create a Linode account and Compute Instance. See our [Getting Started with Linode](/docs/guides/getting-started/) and [Creating a Compute Instance](/docs/guides/creating-a-compute-instance/) guides. 1. Follow our [Setting Up and Securing a Compute Instance](/docs/guides/set-up-and-secure/) guide to update your system. You may also wish to set the timezone, configure your hostname, create a limited user account, and harden SSH access.

File: 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/guides/linux-users-and-groups/) guide. {{< /note >}}

File: Guides Written for a Root User

1 2 3

{{< 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/guides/linux-users-and-groups/) guide. {{< /note >}}

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 24 25 26 27 28 29 30 31 32

## Using MySQL 1. Log in to MySQL as the root user: ```command mysql -u root -p ``` 1. 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. ```command create database testdb; grant all on testdb.* to 'testuser' identified by 'password'; ``` 1. Exit MySQL. ```command exit ``` ### Create a Sample Table 1. Log back in as `testuser`: ```command mysql -u testuser -p ```

Note

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.

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).

Introduce new terms in italics with a * on either side of the term:

1	This guide covers how to install Git, a *version control system*.

Output: This guide covers how to install Git, a version control system.

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.

Commands that are not inline with paragraph text should be displayed with the command shortcode. This shortcode renders the command in a monospaced font with a light or dark background and a copy-to-clipboard button. Unlike other shortcodes (e.g. content, note, caution, etc), the command shortcode should be referenced with Markdown’s code fence syntax.

• Command shortcode example

  1 2 3

  ```command sudo systemctl restart apache2 ```

  The above command shortcode is rendered with a light grey background by default:

  sudo systemctl restart apache2

• Multiline commands

  The command shortcode can accept multiple lines if more than one command needs to be displayed:

  1 2 3 4

  ```command sudo systemctl restart apache2 sudo journalctl -u apache2 ```

  The above command shortcode is rendered as:

  sudo systemctl restart apache2
  sudo journalctl -u apache2

• Command with title

  The title parameter can be used to specify a title that displayed above a command shortcode. This can be useful to label the server or workstation that a reader should execute the command on. For example, some guides instruct the reader to set up multiple servers. Specifying a title can disambiguate which server a given command should be run on.

  1 2 3 4 5 6 7

  ```command {title="Web server"} sudo systemctl restart apache2 ``` ```command {title="Database server"} sudo systemctl restart mysql ```

  The above command shortcodes are rendered as:

  Web server

  sudo systemctl restart apache2
  Database server

  sudo systemctl restart mysql

• Command with dark background

  The class parameter can be used to specify that a command should be displayed with a dark background:

  1 2 3

  ```command {class="dark"} sudo systemctl restart apache2 ```

  The above command shortcode is rendered as:

  sudo systemctl restart apache2

In some existing guides, you may see commands displayed without the command shortcode. In these instances, the commands are simply indented with a tab or four spaces in the Markdown source text. For example:

1 2 3

Run the following command to restart Apache: sudo systemctl restart apache2

The older (tab or four space-indent) syntax should not be used for new content. The code shortcode renders a copy-to-clipboard button for the reader’s convenience, and the old syntax does not provide this feature.

Inline commands should be denoted by backticks.

1	Update your system by running `yum update`.

Output: Update your system by running yum update.

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

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 parameter in the page header. This will automatically 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.

• Link Title 1
• Link Title 2

Using shortcodes, it is possible to extend a Markdown file with another. For common tasks such as basic software installation, consider using the content shortcode. This allows our library to maintain consistent and up to date installation instructions for frequently used tools such as Python, MySQL, and Docker.

Markdown files intended to be inserted into multiple guides are called shortguides. To create a shortguide, create a directory with the name of your shortguide anywhere within docs/, and then create an index.md within the directory for your content (e.g. example-shortguide-name/index.md).

Inserting headless: true in the front matter will hide the guide from the site navigation as well as the search index.

When using the content shortcode in a guide to embed a shortguide, the shortcode will take the name of your guide’s directory (e.g. example-shortguide-name) as a parameter. A shortguide can be within a different part of the docs hierarchy from the guide that embeds it, so the guide directory name exists within a global namespace of all shortguides in the repository. In other words, two different shortguides can’t use the same directory name.

To use an image in a shortguide, add the image to your shortguide’s directory and then use the image shortcode to embed it:

File: sample_embedding_guide/index.md

1	{{< image src="image-name.png" alt="image alt label" title="image title" >}}

The following shortguide describes how to install Python via Miniconda. Create a directory named install_python_miniconda and filed named index.md within it:

File: install_python_miniconda/index.md

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31

--- author: name: Linode email: docs@linode.com description: 'A shortguide that shows how to install Python via Miniconda.' keywords: [] license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' published: 2018-08-23 modified_by: name: Linode title: "Install Python with Miniconda" headless: true show_on_rss_feed: false --- <!-- Installation instructions for Python 3. --> 1. Download and install Miniconda: ```command curl -OL https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh bash Miniconda3-latest-Linux-x86.64.sh ``` 1. You will be prompted several times during the installation process. Review the terms and conditions and select "yes" for each prompt. 1. Check your Python version: ```command python --version ```

To use this shortguide in another guide, use the following syntax:

File: sample_embedding_guide/index.md

1	{{< content "install_python_miniconda" >}}

Use the file shortcode to present code examples, code snippets, and other text file contents in a guide. This shortcode renders the file content with line numbering, a specified filepath, syntax highlighting, and line highlighting. Unlike other shortcodes (e.g. content, note, caution, etc), the file shortcode should be referenced with Markdown’s code fence syntax.

Note

Exceptionally long files should be shown in parts, if needed. In these cases, you can add the entire file to the same directory as your guide and link to it from within the guide.

• File with filepath

  1 2 3 4 5

  ```file {title="/path/to/file.html"} <div> Sample file text </div> ```

  The above file shortcode is rendered as:

  File: /path/to/file.html

  1 2 3

  <div> Sample file text </div>

• File with language/syntax highlighting

  A code language or syntax can be defined with the lang parameter to set how the text is displayed. A list of supported languages can be found on GitHub.

  1 2 3 4 5

  ```file {title="/path/to/file.html" lang="html"} <div> Sample file text </div> ```

  The above file shortcode is rendered as:

  File: /path/to/file.html

  1 2 3

  <div> Sample file text </div>

• File with starting line specified

  If your file snippet represents the middle of a file, you can use the linenostart to specify that the line numbering to the left of the snippet should start at a number other than 1:

  1 2 3 4 5

  ```file {title="/path/to/file.html" lang="html" linenostart="11"} <div> Sample file text </div> ```

  The above file shortcode is rendered with line numbers 11, 12, and 13 instead of 1, 2, and 3:

  File: /path/to/file.html

  11 12 13

  <div> Sample file text </div>

• File with highlighted lines

  The hl_lines parameter can be used to highlight certain lines within the file. The parameter is a space-separated list of strings. Ranges of lines can also be specified:

  1 2 3 4 5 6 7 8 9 10 11

  ```file {title="client/src/Header.js" lang="js" linenostart="11" hl_lines="4-6 9"} import React from 'react'; function Header() { return ( <header> Example header text </header> ); } export default Header; ```

  The above file shortcode highlights lines 4 through 6 and line 9:

  File: client/src/Header.js

  11 12 13 14 15 16 17 18 19

  import React from 'react'; function Header() { return ( <header> Example header text </header> ); } export default Header;

• Using file shortcodes within lists

  If using a file shortcode in a list, each line of the shortcode should start at the indentation level of the list. For example:

  1 2 3 4 5 6 7 8 9

  1. List item 1 1. List item 2 ```file {title="/path/to/file.html" lang="html"} <div> Sample file text </div> ```

In some existing guides, you may see this older shortcode syntax for displaying a file:

1 2 3 4 5

{{< file "path/to/file.html" html >}} <div> Sample file text </div> {{< /file >}}

This is equivalent to:

1 2 3 4 5

```file {title="/path/to/file.html" lang="html"} <div> Sample file text </div> ```

The older syntax should not be used for new content. While they are rendered with the same presentation by Hugo, they are not displayed the same in the GitHub.com UI. When viewing a Markdown file in the library on GitHub, the newer code fence shortcode syntax will have enhanced styling, compared with the older shortcode syntax.

Inline file paths and file names should be formatted as inline code blocks.

Headings should be written in title case and can be up to 3 levels deep.

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: ![Description of the image](filename.png "Description of the image.")
• Over 650 px wide: [![Description of the image](filename_small.png "Description of the image.")](filename.png)

When instructing a reader to press hotkeys or other combinations of keys, enclose each individual key within a kbd html element as shown in the example below.

1	Use <kbd>Ctrl</kbd> + <kbd>C</kbd> to copy text.

Output: Use Ctrl + C to copy text.

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 link example: [Getting Started](/docs/guides/getting-started/)
• External link example: [Apache HTTP Server Documentation](https://httpd.apache.org/docs/)

Ordered lists are numbered and should be used for a series of steps. These lists should be formatted by appending a 1. to the beginning of each step.

1 2 3

1. Step 1 1. Step 2 1. Step 3

Unordered lists are bulleted and should be used for any collection of items that do not necessarily need to be ordered. These lists should be formatted by appending a - to the beginning of each step.

1 2 3

- Item 1 - Item 2 - Item 3

Notes should be important text that does not necessarily fit the narrative of the preceding 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.

1 2 3

{{< note >}} This is a sample note. {{< /note >}}

Note

This is a sample note.

1 2 3

{{< caution >}} This is a sample caution. {{< /caution >}}

Caution

This is a sample caution.

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

1 2 3

| Column Header 1 | Column Header 2| | -- | -- | | **Example** | This is an example of text in the second column. |

1 2 3

| Left-Aligned Text | Center-Aligned Text | Right-Aligned Text | | -- |:--:| --:| | Example | Example | Example |

Output from terminal commands should be displayed with the output shortcode:

1 2 3

```output Hello world! ```

The above shortcode is rendered as:

Hello world!

Here’s an example of a command (using the code shortcode) and its output (using the output shortcode) displayed together:

1 2 3 4 5 6 7

```command echo "Hello world!" ``` ```output Hello world! ```

The above shortcodes are rendered as:

echo "Hello world!"

Hello world!

In some existing guides, you may see this older shortcode syntax for displaying terminal output:

1 2 3

{{< output >}} Hello world! {{< /output >}}

This is equivalent to:

1 2 3

```output Hello world! ```

The older syntax should not be used for new content. While they are rendered with the same presentation by Hugo, they are not displayed the same in the GitHub.com UI. When viewing a Markdown file in the library on GitHub, the newer code fence shortcode syntax will have enhanced styling, compared with the older shortcode syntax.

COPYRIGHT OWNERSHIP. Writer agrees that the Work is being created by the writer for the Linode Guides & Tutorials repository and that each form of Work is being created by the writer as a “work made for hire” under the United States Copyright Act and, at all stages of development, the Work shall be and remain the sole and exclusive property of Linode. At Linode’s sole, absolute and unfettered discretion, Linode may make any alterations to the Work.

CREDIT. Nothing contained in this Agreement shall be deeded to require Linode to use the Work, or any part thereof, in connection with Linode Guides & Tutorials or otherwise. Credit for the Work shall read, “Contributed by [writer’s name].”

PAYMENT. Upon publication of a submission to the Linode Guides & Tutorials Repository, the writer will be paid the sum agreed to by email by both Linode and the author. Author may choose payment either in the form of a credit to their Linode account, a hardcopy check, or as an electronic payment via PayPal.

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.

• GitHub Beginners Guide
• Red Hat Writing Style Guide