A Sysadmin’s Guide to Markdown Language

Bill Kindle

Bill Kindle

Read more posts by this author.

Markdown language, known as “The Formatting Language of the Internet” has become an essential skill for many tech professionals, especially system administrators. With this markup language, system administrators can create blogs, documentation, presentations, resumes, or even entire books!

Do you want to create readable and accessible content using an easy to learn plain-text syntax? If so, keep reading.

In this article, you’ll learn about Markdown language and how, specifically, a system administrator can leverage it. You’ll learn the basics of the Markdown syntax, tools available to help you start creating documents, and get comfortable with writing in plain-text.

You’ll end the article by applying what you’ve learned to a real-scenario by creating a document outlining a simple procedure for a fellow Jr. Sysadmin.

If that sounds interesting and leaves you wanting to get started with creating web-ready, future-proof documents, then keep reading!

Prerequisites

The great thing about Markdown is that it is plain text. Any plain-text editor will suffice. There are popular choices like Visual Studio Code (with Markdown All-in-One extension), Atom Editor, and Dillinger you can use.

All examples shown will be using http://dillinger.io. With this web service, you can begin learning immediately without having to install anything. It has a clean interface and is intuitive to use.

Markdown Language is Great for Documentation

Why should you write in Markdown? Because lots of other people are including some huge organizations. Markdown is used on sites such as Microsoft Docs, GitHub, ReadTheDocs, and even the Linux man-pages. It is hard to find many online documentation resources that are not using some form of Markdown.

Organizations choose to use Markdown because it is easily convertible to HTML. This aspect makes it an excellent choice for web-ready pre-formatted text.

Writing accessible, readable, and easy to distribute documentation should be the primary goal for the Sysadmin, creating content, whether it be a simple README, a record of knowledge related to a server or systems, or a collection of documentation items related to a project.

Markdown is readable by any-plain text application and distributed quickly to the web or other knowledge management systems like Confluence. Markdown language allows the content creator to focus on writing text. A content creator does not need to concern themselves with formatting using menus, alignment, word art, or saving the file in the wrong format.

Learn more about the history behind Markdown here.

Still not convinced? Explore some of the use cases in the next section.

Example Use Cases

Here are just some of the real-world use case examples for using Markdown:

Ready to experience Markdown for yourself? In the next section, you will learn all of the Markdown syntaxes you will ever need to know.

Markdown Language Basic Training

Get ready to go from zero to hero in Markdown syntax knowledge. You will learn the basics that will have you creating professional-looking docs in just a few minutes.

Pick a Markdown Flavor

There are many different implementations of the Markdown syntax. The most common is CommonMark. CommonMark is the origin of all markdown flavors and is the syntax you are going to learn in the following examples.

It’s best to pick a flavor and stick with that syntax throughout a Markdown-formatted document. Each flavor of markdown has a lot of similar syntaxes but also some specific ones as well. Not all rendering engines will work for every flavor, which is why this article is focusing on CommonMark. You can view a full list of Markdown flavors here.

Editors

Markdown is plain-text. A Sysadmin should be familiar with tools such as Notepad / Notepad++ / VIM / Nano. All of these plain-text editors can create Markdown-formatted text files. Markdown language doesn’t require a special editor or viewer; it’s plain-text. That’s the real beauty of this markup language.

The following examples are using Dillinger, an online Markdown editor that shows you a real-time rendering of Markdown syntax. You can use any plain text editor they wish. However, to see live previews of Markdown markup, an editor that supports the live preview feature is needed. See the Additional Resources section at the end of this article for a list of popular choices.

Headings

A heading signifies a section of a document and is the first syntax that you need to learn. For example, this section has a heading H3. Heading levels can go from H1 to H3.

Some Markdown editors and flavors will allow you to use H4, which is not an ordinary header level. WordPress, for example, allows it while Notion, the editor used to create this article before uploading to WordPress, does not recognize it, but will enable you to use #### [text here].

Headings use the hash or pound # character to denote the start of a new section in a document.

H1 would be # H1, H2 would be ## H2, and H3 would be ### H3 respectively. Here’s a demonstration below:

Heading Syntax demonstration using Dillinger.io
Heading Syntax demonstration using Dillinger.io

Now that you can create headers, it’s time to learn how to do basic text formatting in the next section.

Formatting Text

Recall that Markdown is still plain-text. Plain-text has no italics or no bold formatting. There are times when a sysadmin needs to add varying emphasis to text to convey the message. Both bold and italics use the asterisk * character to add emphasis in Markdown.

Italics uses a pair of single-asterisks *italics* and Bold uses a pair of double-asterisks **bold**.

Below is a demonstration on how to use both italics and bolding while typing text:

Formatting text using italics and bold typeface using Dillinger.io
Formatting text using italics and bold typeface using Dillinger.io

Another way to emphasize text is to use a callout or blockquote. To express a blockquote, use the > greater than character. Below is a demonstration of a blockquote used in a block of text:

Demonstration of a blockquote used in a block of text
Demonstration of a blockquote used in a block of text

If you need to document code, you’ll undoubtedly have to learn about the backtick, accent, or grave character [ ‘ ] to document commands and code. To express Inline Code, use two [ ‘ code ‘ ] backticks. Take a look below of how to do this in a block of text:

Formatting inline code using Dillinger.io
Formatting inline code using Dillinger.io

To express a code block, enclose the code between two sets of three backticks or grave accents [ “` ].

Always include the language format tag when expressing a code block in Markdown. Some editors will format code differently, making it easier to read if the language is declared.

Below is a demonstration below of a code block using the PowerShell format tag:

Code block using the PowerShell format tag
Code block using the PowerShell format tag

Linking to resources is sometimes a requirement when creating documentation. Using Markdown, you can link to URLs or even different sections within the same document. Adding a link to an external website can be done with open and close square [ ] brackets and parenthesis ( ) pairs.

The format is [ Alternate Text ] ( URL Here ). Here is a demonstration of creating a link in Markdown:

Creating a link in Markdown
Creating a link in Markdown

Now that you know basic text formatting, it’s time to add some lists and tables in Markdown in the next section.

Lists & Tables

Some elements found in many Markdown-formatted documents are lists and tables. In this section, you will learn how to create unordered and ordered lists. You will also learn how to create a simple table containing data.

You express an unordered list using either the hyphen or minus - or single asterisk * character, followed by the item in the list. Many Markdown editors will automatically create a new item when you press return after using one of these two characters.

You express an ordered list using numbers starting with 1. or 1). Like an unordered list, many editors recognize this combination as an ordered list, and upon pressing the return key, the next number in the list will appear.

Here is a demonstration in creating unordered and ordered lists in Markdown:

Creating unordered and ordered lists in Markdown using Dillinger.io
Creating unordered and ordered lists in Markdown using Dillinger.io

Lists are great, but tables are next-level. Good news! They are quite easy to make, and once you see it, the syntax should feel familiar.

Finally, you can add values for each cell, also enclosing the value in | characters. Below is what a simple table with three columns and two rows looks like:

Tables in markdown comprise of just three characters used in a specific order and format. Those characters are the pipe |, the colon:, and the hyphen or minus - characters. To build a table, you give each column a name, beginning with | and separating each column name with a | and adding another | after the last column name.

| Column 1 | Column 2 | Column 3 |
|:---:|:---:|:---:|
| Value 1 | Value 2 | Value 3 |
| Value 3 | Value 4 | Value 5 |

You can modify table columns and rows by just adding or removing text. Here is a demonstration of adding and removing table data:

Demonstration of adding and removing table data
Demonstration of adding and removing table data

Images

Up to this point, the focus has been on text. However, since Markdown is the formatting language of the Internet, this article needs to mention adding graphics using Markdown syntax. When creating documentation, a sysadmin should include a screenshot of an application or process to demonstrate a point fully. The syntax to add graphics is similar to that of adding a link using Markdown. The only difference is adding an exclamation ! character.

You add an image to a document by using the below example:

![Alt Image Text](<http://url/a.png>)

It’s best to use a URL for images so you can focus on text and not images in a directory. However, you can include images in the same directory as the markdown using the path.

Apply Your Knowledge

Now take what you’ve learned so far and apply it to the following scenario. You can do this on your own or skip ahead to the example at the end. Head over to Dillinger.io

Scenario

You have a process for a Jr. Sysadmin that needs documented. The process document needs to include the following:

  1. A brief description of the process and headers for each section.
  2. A checklist consisting of 3 items.
  3. A table consisting of some expected configuration data to use as a reference.
  4. An ordered list outlining the process.
  5. An image related to the process.
  6. A link to a URL.

Take a moment to refer back to the syntax you just learned, and try creating this document. Here’s one example I created:

# Adding a PowerShell Scheduled Job

## Description

This process outlines the steps required to setup a *Scheduled Job* using **PowerShell**. 
We use scheduled jobs as part of many maintenance processes performed by the team daily.
It will be beneficial for you to keep this document handy as a **Jr. Systems Administrator**. 

### Pre-Op Checklist

- Verify the maintenance window has been approved by change control board.
- Verify that notifications have been sent to stakeholders.
- Verify that you have the proper access to systems affected.

**If all of the above criteria has been met, proceed with configuring the PowerShell Scheduled Job**.

| Scheduled Time | Job Name | User Account | Will Email Be Sent? |
|---|---|---|---|
| 09:00 PM EDT | Stop IIS Services | SYSTEM | Yes |
| 09:30 PM EDT | Release WSUS Updates / Deadline | SYSTEM | No |
| 11:00 PM EDT | Start IIS Services | SYSTEM | Yes |

## Steps to Add Scheduled Job

## Steps to Add Scheduled Job

Execute the following steps to add a PowerShell scheduled job:

1. Open Windows PowerShell
2. Enter the following command and press **Enter**: 
```powershell
    $O = New-ScheduledJobOption -WakeToRun -StartIfIdle -MultipleInstancePolicy Queue
    $T = New-JobTrigger -Weekly -At "9:00 PM" -DaysOfWeek Monday
    $path = "\\Srv01\Scripts\Stop-IISServices.ps1"
    Register-ScheduledJob -Name "UpdateVersion" -FilePath $path -ScheduledJobOption $O -Trigger $T

3. Verify scheduled job is active using Get-ScheduledJob and inspecting the list of jobs.
4. Notify Sr. Systesm Administrator that task is complete.

Save the file with the .md extension and any Markdown viewer can read it. Here’s what the rendered document would look like:

Sample Markdown rendering.
Sample Markdown rendering

You didn’t have to open Microsoft Word or some fancy knowledge management application. You used a plain-text editor and saved the file as Markdown.

Conclusion

Creating documents can be annoying. Learning Markdown is an easy-to-learn markup language and one of the most valuable skills a modern Sysadmin should have. Creating documentation is something every good Sysadmin regularly does. But creating proper documentation that not only looks good but works with any plain-text application available is a sign of professionalism. Markdown takes the boring out of documentation.

In this article, you learned about Markdown and the advantages of using this markup language as a Systems Administrator. You’ve learned the many ways that Markdown can create rich web-ready content using a plain-text editor. You also learned the basics of Markdown formatting using the CommonMark syntax. Now get out there, and practice what you’ve learned. Make documentation great again!

Additional Resources

Here are a few resources for you to check out organized by category. Enjoy!

Markdown Editors

The following editors are browser-based and require no additional software installation:

The following editors require installation or additional extensions:

Markdown Cheat Sheets

Converting Markdown Files

Pandoc works standalone and as a Visual Studio Code extension.

Making Markdown Slide Decks & Presentations

Have suggestions? Leave a comment!

Subscribe to Adam the Automator

Get the latest posts delivered right to your inbox

Looks like you're offline!