An Introduction to Markdown

Posted on by | Leave a reply

This past February, I was putting together a proposal for the 2022 Distance Teaching & Learning (DT&L) Conference, and I shared my draft with a couple of my colleagues for feedback.

Typically, when requesting feedback, our team relies on Google Docs, which has a nice feature set for suggesting edits.

However, I was not using Google Docs. I explained that they would be viewing my formatted document on HackMD, a collaborative web-based Markdown tool.

One of the colleagues I had asked for feedback responded:

What are the pros and cons compared to a google doc, may I ask?

That question inspired this blog post.

What is Markdown?

Markdown is a plain text format with a simple syntax to add formatting elements (headings, lists, quotes, bold, italics, etc.). It is easy to convert Markdown files into other formats, such as PDFs, HTML, and rich text. One of the primary uses of Markdown is creating content for the web, which can be done with almost no knowledge of HTML. The first Markdown specification was developed by John Gruber and Aaron Swartz in 2004 and released as Open Source.

What Are the Advantages of Writing in Markdown?

It Is Easy to Learn and Fast to Write

Most markdown syntax is intuitive. Perhaps you are writing a document, and you decide you want to emphasize some text using bold or italics styling. In Markdown, you can surround the words with underscores or asterisks rather than select content and apply a style from a menu or keyboard command. For bold text, add either two asterisks or two underscores before and after the word (your choice, most editors support either syntax):

**bold**
__bold__

For text that you want to be displayed in italics, use one underscore or asterisk before and after the word:

*italics*
_italics_

Creating hyperlinks in documents, a somewhat tedious process in a word-processing program or HTML, is as easy as putting a descriptive link text in brackets and then an address immediately following in parenthesis, like this:

[OSU Canvas Dashboard](https://canvas.oregonstate.edu/)

which in my document becomes: OSU Canvas Dashboard.

It Is Just a Text File

A Markdown file with the extension “.md” is just a plain text file. Storing information in plain text files has several advantages:

  1. Text files are future-proof. You can open a plain text file with any editor on any platform. You are not hostage to the proprietary format chosen by an application developer. You are not dependent on any particular software program still being around to open your Markdown files.
  2. Text files require very little storage. This blog post, written in Markdown, was almost 250% larger once converted to a Microsoft Word document.
  3. Text files are platform-agnostic, making them easy to share with other people or multiple devices. A text file can be opened on a Mac, on Windows, in Chrome OS, in a web browser, on an ios or Android smartphone, or on a Linux machine.
  4. If you open up one of your Markdown text documents in platforms like Box or Dropbox, it automatically renders the HTML.

Markdown is Highly Portable

One of the most significant advantages to writing in Markdown is how easy it is to convert Markdown into virtually any other file format:

  • HTML: With no knowledge or experience in web development, you can quickly convert Markdown to HTML. There are many ways to convert Markdown to HTML. You can use a web-based tool such as Markdown2Html or StackEdit or work in a text editor with support for exporting Markdown in various formats like Brackets.
  • RTF: An RTF file keeps basic formatting, such as links or emphasis, while retaining a text file’s flexibility and small size.
  • PDFs: Many Tools support applying CSS-based styles during a conversion. On my Mac, I use Marked 2 and several of the Marked 2 – Custom Styles to create beautiful PDF files.
  • Word: Markdown formatting information (titles, headings, quotes, paragraphs, lists, etc.) is retained during conversion. Suppose you convert a document from Markdown to Word. You can then apply any of the built-in styles available in Microsoft Word to format your file instantly.

For a much longer list of the supported conversion file types, explore Pandoc, a universal conversion utility. Using Pandoc, I have converted markdown files into a slide deck, a mind map, a Google Doc, and a Microsoft Word doc, but there are dozens of additional options.

It Is Easier to Read and Write Than HTML

Let’s look at a numbered list with some simple formatting. I have applied bold to item 1 and italics to item 4:

  1. Analysis
  2. Design
  3. Development
  4. Implementation
  5. Evaluation

Here is what that list looks like in Markdown:

1. **Analysis**
2. Design
3. Development
4. _Implementation_
5. Evaluation

If you were to write that same list in HTML, it would look like this:

<ol>
<li><strong>Analysis</strong>
</li><li>Design</li>
<li>Development</li>
<li><em>Implementation</em></li><li>Evaluation</li>
</ol>

Even if you are comfortable coding in HTML, writing the list in Markdown is much quicker and can be quickly converted to HTML at any time.

You Can Write Without Distraction

Using Markdown, I can focus on content rather than the formatting. I can indicate how something should be formatted (as a hyperlink, heading, paragraph, etc.) and then let a MarkDown tool transform my document to numerous other file types. I don’t have to look at dozens of text and paragraph formatting options on a ribbon toolbar or interrupt my writing to apply them.

What Do You Need to Get Started?

A Text Editor

You can write Markdown in any text editor. However, many tools provide a real-time preview of your formatted document and give you several export options. These web-based Markdown tools are free options worth exploring:

  • Dillinger is a great place to start. You can experiment with the syntax and instantly preview your content without installing any software on your computer. StackEdit works much the same way. Both are free, and both support export to HTML and PDF.
  • HackMD is another web-based tool, also free, which has collaborations options.

If you prefer working in a desktop application, there are also many options. Here is a nice write up of several Markdown Editors.

Learning the Syntax

After choosing your editor, you need to get familiar with some basic syntax. The most common and helpful Markdown syntax is very easy to master. You saw bold, italics, and a Markdown link earlier. Here are a few more examples:

Headings

To place a heading in the document, precede the text for the heading with one or more hashtags. Here’s a level two heading:

Level Two Heading

In Markdown, you would write it like this:

## Level Two Heading

Many Markdown editors also support the use of an id in a heading:

### Level Three Heading {#custom-id}

When converted to HTML, this will give you an anchor that you can use to link directly to that heading.

<h3 id="custom-id">Level Three Heading</h3>

Lists

Lists look much like they would in any other document. Here is a numbered list:

  1. trumpet
  2. french horn
  3. tubal
  4. trombone

which in Markdown is:

1. trumpet
2. french horn
3. tuba
4. trombone

and an unordered list:

  • cymbal
  • drum
  • marimba
  • tambourine
  • xylophone

looks like this in Markdown:

- cymbal
- drum
- marimba
- tambourine
- xylophone

Or you can use the single * with a space to make a list of items like this:

* string instruments
    * cello
    * violin
    * harp

Note the support for indenting lists using spaces in the example above, which would work with either * or -. The Markdown list above would render like this:

  • string instruments
    • cello
    • violin
    • harp

Hyperlinks

To make a hyperlink in Markdown, you write a descriptive title in brackets, followed by the URL in parenthesis, as mentioned above. You can even save yourself the trouble of manually creating markdown links through the use of one of the many available browser extensions like this one for Chrome or this one for Firefox, which allow you to copy a website address as a Markdown link.

Rather than document the complete set of Markdown formatting options, I will refer you to the Markdown Basic Syntax Guide or in Markdown:

[Markdown Basic Syntax Guide](https://www.Markdownguide.org/basic-syntax/)

MultiMarkdown: An Expansion of the Language

The Markdown language is Open Source. Since its inception, other developers have enhanced the language to include options beneficial to academic writers. These include:

  • tables
  • blockquotes
  • citations
  • footnotes [^1]

Adding specific examples of these items is beyond this basic Markdown blog post. Instead, I recommend reviewing the MultiMarkdown v6 Syntax Guide. As you will see, the syntax for the new items follows the same spirit of being easy to add to a document and relatively intuitive syntax.

Advanced Tools and Applications

If you want to do a deep dive on Markdown, here are a few resources you can explore:

Yes, But What Are the Cons?

You may recall that my colleague asked about the pros and the cons. So, as much as I love writing in Markdown, I should be transparent about the limitations I have encountered.

  1. Collaboration. Both Microsoft Word and Google Docs support providing feedback on documents using the review or suggestion features. I have yet to find a Markdown editor that supports this type of collaboration. When I want to have a document reviewed, I convert the Markdown document to one of those other formats and then convert it back after implementing the feedback. Converting from Markdown to something, as I have said, is something most markdown editors already do. Converting from some other format to Markdown may take more effort. In this case, I used a Google Doc add-on, Docs to Markdown.
  2. Citation tool support. When writing in academia, I use an integrated tool for citation. Zotero, when installed as an add-on to Word or Google Docs, will help generate bibliographies and inline citations. I have managed to integrate Zotero integrations into my Markdown editor of choice (Visual Studio Code), but it was very fiddly. I followed the setup described in this video: Setting Up a Scholarly Writing Environment With Markdown, VSCodium, and Pandoc. Not for the faint of heart, with a very detailed how-to, step-by-step video, it still took me the better part of a Saturday, with reasonably in-depth knowledge of Markdown, Zotero, and my editor.

Conclusion

To begin your Markdown journey, I suggest starting here: Markdown Guide. The easiest way to learn Markdown is to start using it; you can learn the basics in minutes. Once you do, you will find broad application and support. You can use Markdown to write HTML, draft blog posts, create documentation, and post messages on messaging platforms or forums such as Reddit, Discord, and GitHub.

[^1]: It seems worth mentioning, in a footnote, that I wrote this blog post entirely in Markdown. Feel free to download it and take a look. To see it with the formatted HTML, try pasting it in the online markdown editor Dillinger.

Print Friendly, PDF & Email

Leave a reply