What is Markdown Syntax?

What is Markdown Syntax?

What is markdown syntax

Markdown is a popular way of adding formatting such as headers, lists, emphasis, blockquotes, links to URLs and images, and more to a plain text document. It was originally designed to be an easy alternative to HTML, but has gained popularity as a way to write structured content, organise notes, quickly create to-do lists, and much more.

In this article, we’ll look at the role Markdown can play in your daily workflow, teach you the basic Markdown syntax to get you started, and finally recommend some great Markdown editors you can try.

You might also like: The Essential List of Resources for Shopify Theme Development

The history of Markdown

Markdown syntax was developed by John Gruber and released in 2004. Gruber had grown tired of the effort involved in producing well-formed HTML and set out to create a syntax and conversion tool that simplified the process.

Here’s how he describes it:

Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).

Industry veterans will notice how he refers to XHMTL. This is because HTML5 was a long way off on the horizon when Markdown was released.

What is markdown syntax? Gruber's own markdown page was written in markdown

Today Markdown has gone beyond its one-sided relationship to HTML and can be found in everything from content management systems and to-do lists apps, to note-taking and writing tools. Let's take a look at how you can start using it today.

How to write Markdown syntax

If you are new to Markdown, here’s a quick overview of commonly used formatting:


To create a top-level heading you use the hash symbol. One hash represents an h1, two an h2, and so on. This works through to a level 6 heading.

# This is an <h1> tag
## This is an <h2> tag
###### This is an <h6> tag


We can apply emphasis in two ways — bold and italic. As you can see in the example below, these can also be combined.

*This text will be italic*
_This will also be italic_
**This text will be bold**
__This text will also be bold__
_You **can** combine them too_


Lists come in two flavours, just as in HTML — unordered and ordered. You can use the * and - characters for unordered list items.

Note that there’s no need to worry about opening a list with a special character. For ordered list items, simply use the relevant number followed by a period.

Most Markdown editors will understand you are creating a list and will, on carriage return, add the relevant next list item in for you (either an ordered or unordered item).

1. Unordered

* Item 1
* Item 2
- Item 2a
- Item 2b

2. Ordered

1. Item 1
2. Item 2
3. Item 3
   * Item 3a
   * Item 3b


Whilst you can’t view an image in a plain text file, it’s very simple to reference one using Markdown.

![Shopify Logo](http://shopify.com/images/logo.png)


Links follow a similar format to images but without the leading bang !.

[Shopify Partner Program](http://shopify.com/partners)


Finally, block quotes are simply prefixed by the > symbol.

> "So we beat on, boats against the current, borne back ceaselessly into the past." - F. Scott Fitzgerald

This is just a taste of what can be achieved in Markdown. You can learn more advanced syntax on John Gruber’s Daring Fireball site.

From HTML to everywhere

Many of you might be wondering what all the fuss is about — after all, most apps and writing tools offer up a toolbar full of formatting functions.

Talk to any ardent fan of Markdown and you’ll hear most of them say that the main reason they love the language is that your fingers never have to leave the keyboard. There’s no need to grab the mouse, navigate to the toolbar, click a button, and then go back to writing. Less interruptions means more focus, and more focus means better flow.

Given that most Markdown editors highlight formatting, it’s even easier to distinguish different elements. For example, here’s a recent article from this blog written in Markdown as viewed in the Ulysses Mac app.

What is markdown syntax? The headline and inline code is easy to read

Benefits of using Markdown syntax

Asides from helping your writing process, there are many reasons that it’s worth adding Markdown to your skill set:

  • It’s intentionally simple - The syntax is no more complicated than creating a hashtag.
  • It’s readable - Once you understand the way Markdown is created, you’ll instantly be able to understand the intended document structure.
  • It’s fast to create - With a handful of constructs for everyday use, there’s not a lot to forget — creating a well-structured document becomes second nature.
  • It’s multi-platform - Markdown documents are plain-text files and are cross-platform by default. You can edit them in any text editor, or use one of the many Markdown writing apps available.
  • It’s easy to share - Being plain text, there’s no need to worry about your recipient being able to open the file.
  • It’s reliable - When converted to HTML, you are safe in the knowledge that the output will be perfectly formatted.
  • It’s widely used - From GitHub to Dropbox, Markdown is used and recognized in an increasing number of online applications.

Multiple output formats

Given its universal nature (it’s just plain text), a whole raft of applications have embraced Markdown and are able to output its content into a variety of formats.

This document, for example, was originally created in the Ulysses Mac application which allows you to output a Markdown file into the following formats:

  • HTML
  • RTF
  • ePub
  • PDF
  • DocX
  • Medium (via their API)

This is another great reason to start writing your content in Markdown — write once and publish elsewhere in a variety of formats.

On a final publishing note, I strongly recommend investigating GitBook. It’s an online service created for building beautiful books using Git and Markdown. It can generate your book in many formats: PDF, ePub, .mobi, or even a website.

Markdown Editors and Apps

When it comes to Markdown editors and apps, the Mac platform wins out. Many apps are also available for iOS and offer iCloud syncing, allowing you to create notes on the move and have them on your desktop when you return home.

Here are a few for your consideration — most of which I have bought and tried myself:

Atom (Open Source)

A cross-platform text editor from GitHub. Supports hundreds of packages including a Markdown preview package. Pressing ctrl-shift-m will open a new tab with the rendered HTML.

Byword ($11.99)

Available for Mac, iPhone, and iPad. Byword allows you to write and publish to a variety of blogging platforms including WordPress and Tumblr. You can also export to HTML, PDF, and rich text. Syncing is available using iCloud and Dropbox.

Desk ($9.99)

Desk was awarded “Best App” by Apple for a second year running. It’s a very easy to use writing app and allows you to publish directly to a variety of platforms including WordPress, Facebook, Squarespace, Evernote, and Medium. With just enough customization options to make it your own, it’s great value.

Focused ($44.10)

Some of you may have encountered Focused under its previous guise, Typed. Realmac Software recently sold the app to 71squared who have rebranded it as Focused. It’s billed as “not just a distraction-free writing app — it’s the first writing app that actually aids your focus.” Its Zen mode lets you select audio tracks to keep you focused and can be an interesting addition to your workflow.

iA Writer ($22.99)

Now at version 3, the Writer is available on Mac and iOS. Version 2 was a little hit and miss for me as it focused on different “writing modes.” However, it’s back at its best in the latest release. With the much-welcomed addition of file management, document export, and powerful text manipulation, it’s a fantastic tool for writers.

Letterspace ($9.99)

A Mac and iOS app that provides “a noise free space to jot things down.” Featuring sync via iCloud, it’s a beautifully designed simple note-taking application that allows you to use Markdown to get your ideas down quickly.

Ulysses ($51.99)

Weighing in with a hefty price tag for a Mac app, I am still more than happy to recommend Ulysses. I’ve been using it for the bulk of 2015 and it’s more than paid for itself. The app is far from basic and includes a wealth of features — many of which you will find yourself using daily.

As well as offering all the standard Markdown syntax highlighting, it features a powerful file management sidebar, syncing via iCloud, customizable themes, and as I mentioned earlier, will output to a wide range of formats. The ebook output is very impressive and well worth considering if you are in publishing.

What about Windows?

You may have noticed that the majority of the apps featured above are for Mac and iOS. If you are a Windows user, SitePoint recently published an extensive list of Markdown editors that you can use.

Dillinger Markdown Conversion Tool

If you prefer to work online, then the Dillinger is a great option. Its creator describes it as “an online cloud-enabled, HTML5, buzzword-filled Markdown editor.” Whether or not you choose to compose online, it’s a great tool for taking a Markdown file and rendering into HTML.

What is markdown syntax? Dillinger markdown conversion and export tool

Dillinger also offers the option of exporting to HTML and PDF, as well as the facility to save your files to services including Dropbox, Google Drive, GitHub, and OneDrive.

Get started with Markdown syntax today

As you have hopefully seen, Markdown has a whole raft of uses today — from writing README files for your GitHub repos, to creating books that will end up as websites, ebooks, and PDFs. It’s easy to learn, easy to use, and a great addition to your skill set.

How do you use Markdown in your development workflow? Let us know in the comments below.

You might also like: Using Git to Simplify Shopify Theme Deployment

About the Author

Keir is based in the UK and works on the Partner Community Team at Shopify. You'll often find him at conferences and running workshops on Shopify theme building. You can subscribe to his newsletter, read his latest articles on his blog, listen to his podcast, and follow him on Twitter.

Grow your business with the Shopify Partner Program

Learn more