Getting Started with Markdown: A Step by Step Guide

Are you new to technical writing and want to master some of the required skills to thrive in the industry? You need a good understanding of Markdown.

Technical documentation is by far different from regular content and in most cases, you will find yourself working closely with developers and experts in the tech industry. As such, your content will tilt towards complex tech terms and software. You want to familiarize yourself with some of the nitty-gritty of the industry. First, knowledge of HTML is important as this is most likely what you will use in writing your content.

However, if you find this challenging, Markdown is your next best bet. Writing documentation is easier with Markdown due to its flexibility and user-friendliness.

This documentation explains Markdown and the five common syntaxes you need to know to use it.

There are different Markdown-supported software - GitHub Wiki, Auto-Open Markdown Previewer in Visual Studio Code (VS Code), Atom, Azure, and StackEdit. But in this document, we'll be using StackEdit.

Prerequisite

Sign up on StackEdit from StackEdit.io and create your account to practice the Markdown syntaxes explained in this documentation.

What is Markdown?

Markdown is a simple text formatting and conversion tool used to write technical documentation or web content. It is a lightweight markup language that describes how a text should appear on the screen. Although, Markdown uses specific syntax, the idea behind this is not for the text to appear with tags and formatting instructions after publication. But for it to be plain and readable. No one but you should know that the documentation is markup with tags and instructions.

Markdown Syntax

The first few Markdown syntaxes to learn are the basic ones used when writing any content. These are:

headlines;
bold & italic;
table;
links;
list;

Headlines

The go-to way to write headlines in Markdown is to add a hashtag before the word/words you want as your headline. The number of hashtags you add depends on the type of headline you want to create. The table below shows the Markdown syntax and the result in HTML:

The first heading with just one hashtag indicates H1, the second with two hashtags indicates H2, the third with three hashtags indicates H3, and so on.

Bold & Italics

To make a word/words appear in bold or italics, the Markdown syntax includes:

For bold: place two asterisks ** at the beginning and end of the word/words you want in bold;
For italics: place an asterisk * at the beginning and end of the word/words you want to italicize. See the table below for these Markdown syntaxes and their result.

Tables

Creating a table with Markdown is a little tricky. However, the best way to learn this is to remember that only two syntaxes are needed: the slash sign | and the dash sign -. The steps below explain how to use these two signs:

Enter your spacebar, followed by a slash |, and click the spacebar again. Then write the title of your first table;
Enter your spacebar, followed by a slash |, and click the spacebar again. Then write the title of the second table;
Repeat the process until you have created the title for as many rows as you want.
After you've created the rows and titles, click spacebar, followed by a slash |, and then enter the dash sign- at least twice. After this, click spacebar followed by a slash |, and the spacebar again.
Repeat this process until you have created the columns for the number of rows you have. The image below shows the Markdown syntax and the result in HTML:

Note: in the screenshot above, I didn't enter a name in the first space of my table. This is because I want to define the title of the sentence in each row and make my table neat.

List

To create a list or bullet points with Markdown,

Use the asterisk sign at the beginning of the word for bullet points.
Use your number keys at the beginning of the words for numbered list.
When you click enter to go to the next line, the list automatically continues.

Note: asterisks are used to create bold, italics, and lists. However, unlike bold and italics, when creating a list of bullet points, you don't add the asterisk at the end of the word.

The table below shows the syntax and result for your numbered and bullet list:

The five syntaxes explained above are the most common ones you'll use if you are just getting started with Markdown for your documentation. The key is to know the different syntaxes and their individual functions and outputs. For more information on Markdown syntax, check the list of resources mentioned below.

Advantages of Markdown

Aside from being the go-to language for software documentation, below are some of the advantages of using Markdown;

Easy to Use

Markdown is very easy to use for beginners in technical writing. It simplifies the process of creating software documentation with zero knowledge of HTML. Beginners yet to master HTML can easily work with Markdown.
No distractions

With Markdown, you write without tedious HTML distractions like tags, brackets, and elements. The syntax is pretty easy and beginner friendly.
No-code Text Editor

If you are familiar with HTML, the code <h1>This is heading</h1> means the text between the two H1 tags should be a header. Working with codes like this can easily confuse starters. A simpler way to achieve this with Markdown is to use the hashtag # without necessarily closing the text with another hashtag or syntax.
Multiple Publication Option

Writing with Markdown doesn't limit your publication option. With Markdown, you can export your document as HTML, PDF, EPUB, Docx, etc.
Highly Supported in Programming Tools

Writing with programming tools like GitHub and Azure is easier as the syntax for formatting text is Markdown.

Conclusion

Markdown offers easy-to-use syntaxes to write documentation without dealing with the hassle of including codes, tags, and brackets. The syntax allows for easy flow in your writing process and enhances the quality of your documentation. If you struggle with HTML, try Markdown.

Below are some resources for a better understanding.