A beginners guide to Markdown for technical content writers

Scope

This document explains how to use the Markdown syntax for creating and formatting written content.
It is aimed at the following audiences:

• technical writers

• software developers

• bloggers

• copy writers, and other web content creators.

Introduction

As a writer, the importance of a properly formatted document cannot be overstated, because a poorly formatted document, no matter how essential its content, will not get the required attention. However, writing and formatting documents using traditional WYSIWYG methods can be demanding and time consuming, especially when working on extensive files. Therefore, we will explore the Markdown syntax and its advantages over the WYSIWYG method of writing and formatting documents.

What is Markdown?

Markdown is a light-weight markup language that allows writers to create well-structured and formatted documents, using simple and easy-to-read syntax.
Invented by John Gruber in 2004, the language has become widely used for creating various types of documents, such as academic papers, technical documentation, blog posts, and more.

Benefits of using Markdown

Due to its simplicity and efficiency, Markdown has become popular among web and technical content writers.
Some benefits of using the Markdown syntax are:

• Ease of learning: Markdown is a simple syntax language. It is easy to use and has a gentle learning curve. You do not require complicated tools or software to create formatted documents.

• Portability: Markdown files (files with .md extension) are not platform or format restricted. You can run them on any device and easily convert them to other formats such as HTML, PDF, or DOCX. This makes it easy to share and collaborate on documents across diverse platforms.

  The use of the Markdown syntax has since been adopted by many websites and platforms, including GitHub, Reddit, and Stack Overflow. Thus, making it a popular choice for creating content for the web.

• Productivity: Markdown allows you to focus on creating clear and concise content for your document, rather than spending time on formatting. It also enables you to create headers, lists, links, images, and other elements using simple syntaxes such as hash symbols (#), hyphens (-), asterisks (*), and brackets [] / ().

• Version control: You can also manage and track your Markdown files by using version control softwares such as Git. This makes it easy to collaborate with other writers and track changes made to your documents over time.

Getting started with Markdown

To get started with the Markdown syntax, you need to download and install a plain text editor with support for Markdown files.
For this document, we will use the VS Code editor.
To setup your work environment, follow the instructions below:

1. Download and install VS Code editor

2. Install markdownlint-VS Code extension

Other plain text editors include:

• Sublime Text

• Atom

Basic Markdown syntax

Here are some basic syntaxes that you will be using frequently while writing your documents in Markdown:

• Headers

  Headers are one of the most important features commonly used when writing. They usually act as titles and subtitles to provide an organizational overview of the document, and also show a logical procession of ideas.
  There are six header sizes ranging from H1 (largest) to H6 (smallest). To create a header, preface your header text with the hash symbol (#), followed by a single spacing.
  The number of hash symbols used indicate the size of the header that you intend to create.

    # Header one (H1)  
    ## Header two (H2)
    ### Header three (H3)
    #### Header four (H4)
    ##### Header five (H5)
    ###### Header six (H6)
  

  https://codepen.io/leo9947/pen/mdQoOmb

• Emphasis and strong emphasis

  Emphasis and strong emphasis are popularly known as Italics and Bold respectively.
  To Italicize a word or phrase in Markdown, surround it with an asterisk (*) or an underscore (_).

     _I am beginning to enjoy learning the Markdown syntax_
                        OR
     *I am beginning to enjoy learning the Markdown syntax*
  

  https://codepen.io/leo9947/pen/ZEmPBXv

  Similarly, to embolden a word or phrase in Markdown, surround it with double asterisk (**) or double underscore (__).

  Formatting document is easier when using the __Markdown syntax__ 
                                   OR 
                   To get started **Click Here**
  

  https://codepen.io/leo9947/pen/GRweNyJ

  Finally, you can italicize and also embolden selected words or phrases by surrounding them with triple asterisk or triple underscore.

  You can ***italicize*** and ___embolden___ text using the **Markdown syntax**
  

  https://codepen.io/leo9947/pen/OJaqbvN

• Links

  Markdown makes use of two types of link styles when linking to external resources. They are the inline link and reference link.

  • Inline link

    To create an inline link, use the square bracket [] and parentheses (). Insert your link text within the square bracket, and your link address within the parentheses.

    [Google](google.com) is the world's most popular search engine.
    

    https://codepen.io/leo9947/pen/oNQVYyR

  • Reference Link

    To create a reference link, use two square brackets [][]. Insert your link text in the first square bracket, and your reference text in the second square bracket. You should then define your reference text at the bottom of your document with the correct link address to an external resource.
    The reference link style is recommended if your document contains multiple link texts that lead to the same external resource. If you ever need to update the link address, you will only have to update the reference link once at the bottom of the document.

    Here is a [link][markdown] to the official Markdown documentation.
    
    [markdown]: link URL
    

    https://codepen.io/leo9947/pen/ExOMNpO

• Images

  Adding images to your document is similar to creating Inline links, but with only a minor difference. To add an image to your document, place an exclamation mark (!) before the square bracket [] and parentheses ().

  However, unlike links, this square bracket will contain your Alt text rather than the link text, while the parentheses will contain your image URL.
  The Alt text, although not compulsory, describes the content of your image should it fail to load on the user's screen. This enables screen reading tools to describe your image to visually impaired users.

  ## Here is a cute picture of my favorite animal
  
  ![Cute dog](image URL)
  

  https://codepen.io/leo9947/pen/bGQZBJR

• Block quotes

  Block quotes are sentences or paragraphs that have been pulled from another source. They are strategically designed to draw the readers attention.
  To add a block quote to your document, preface the quote with the greater-than symbol (>).
  If the quote spans multiple paragraphs, place the symbol before each new paragraph.
  Other Markdown syntaxes can also be used within a block quote.

  lorem ipsum is simply a dummy text of the printing and typesetting industry. Lorem has been the standard dummy text ever since the 1500s. Lorem ipsum dolor sit amet, consectetur adipisicing elit. Deserunt sint accusamus libero unde necessitatibus quidem eos dolorum dolore ratione commodi, itaque dolor voluptas officiis suscipit molestias optio obcaecati perferendis error.  
  
  > "success is not final, failure is not fatal: It is the courage to continue that counts." **-Winston Churchill** 
  
  It is a long established fact that a reader will be distracted by the readable content of a page. Lorem ipsum dolor sit amet, consectetur adipisicing elit. Deserunt sint accusamus libero unde necessitatibus quidem eos dolorum dolore ratione commodi, itaque dolor voluptas officiis suscipit molestias optio obcaecati perferendis error.
  

  https://codepen.io/leo9947/pen/XWyGNwy

• Lists

  Lists are used to outline important ideas, as well as add passive space to your document. This enhances readability and prevents cluttering. There are two list styles, and they are ordered and unordered lists.

  • Ordered list

    Use ordered lists if your list items must follow the specified order in which you are listing them.
    To create an ordered list, preface the list item with a number and a period followed by a single spacing.

     Here is a step-by-step process for installing windows 10:
    
     1. Ensure that your device is compatible
    
     2. Create a new folder
    
     3. Buy a new software
    

    https://codepen.io/leo9947/pen/XWyGpdG

  • Unordered list

    Use an unordered list when the order in which the list items appear is of no consequence.
    To create an unordered list, preface the list item with either an asterisk (*), hyphen (-) or a plus (+) symbol followed by a single spacing.

       Here is a list of the Markdown syntaxes that we have covered so far:
       * Headers
       * Bold and italics
       * Links
       * Images
       * Lists
    

    https://codepen.io/leo9947/pen/jOQJyVK

• Task list

  You can also create a list of tasks or to-do items using Markdown, which is then ticked off as you complete each task.
  To create a task list, preface the to-do item with a hyphen (-) or asterisk (*) followed by a space and a square bracket [].
  To mark a task as complete, add an x inside the square bracket [x]; for a pending task, leave the square bracket empty [ ].

  * [x] This task has been completed
  
  * [ ] This task is yet to be completed
  

  https://codepen.io/leo9947/pen/jOQJyVK

• Code

  With Markdown, you can differentiate regular text from code by enclosing the text within a pair of backticks (`).
  For example: var firstName = 'Jane'

  If the code block spans multiple lines, enclose the text within three backticks (```) instead of one.

  var firstName = 'John';  
  var lastName = 'Doe';  
  console.log(`${firstName} ${lastName}`);
  

  https://codepen.io/leo9947/pen/qBQwYwP

• Subscript and Superscript

  Finally, you can also use subscripts and supercripts in Markdown.
  To write a character as a subscript, enclose the subscript character within a pair of tilde symbol (~).

  This is the chemical symbol for hydrogen gas (H~2~)
  

  To write a character as a superscript, enclose the superscript character within a pair of caret symbol (^).

  The correct answer to this expression - 8^2^ is 64
  

• Conclusion

  Knowledge of the Markdown syntax is a valuable skill for anyone who intends to create a well-formatted, visually appealing content with minimal effort.
  It offers a simple, yet intuitive way to structure and style your text without the need for HTML or other complex formatting tools.
  Due to its portability, Markdown is widely supported across diverse platforms and applications, making it a versatile choice for writers, bloggers, developers, and other web-content creators.
  Its readability, both in its raw form and rendered output, makes collaboration and version control straightforward.
  So, start using Markdown today and enjoy the seamless experience of crafting compelling written content with ease. ```