What is Markdown, and Why is it Awesome?

Published Sep 12, 2017 by in Markdown, Marked2, Emacs, Vi at https://preview.rmoff.net/2017/09/12/what-is-markdown-and-why-is-it-awesome/

Markdown is a plain-text formatting syntax. It enables you write documents in plain text, readable by others in plain text, and optionally rendered into nicely formatted PDF, HTML, DOCX etc.

It’s used widely in software documentation, particularly open-source, because it enables richer formatting than plain-text alone, but without constraining authors or readers to a given software platform.

Platforms such as github natively support Markdown rendering - so you write your README etc in markdown, and when viewed on github it is automagically rendered - without you needing to actually do anything.

I’ve used Markdown for years now, after being introduced to it at my previous company. When I worked as a consultant I would be delivering client reports, and I wrote all of them in Markdown. The final delivered copy was in DOCX or maybe HTML - but the master copy remained as Markdown.

How Do I Write Markdown? 🔗

There’s a comprehensive reference guide here.

	Markdown is normal text, with characters like asterisks around phrases for bold and _underscores for emphasis_.

	[Links are easy](http://google.com) as are images:

	![crab](https://rmoff.net/content/images/2016/04/IMG_1036.JPG)

	You can do code blocks by indenting the code with a tab or four spaces:

	SELECT 42
	FROM FOO;

	And many markdown interpreters support the ``` notation to surround a code block and will apply syntax highlighting as well

	```sql
	SELECT 42
	FROM FOO;
	```

view raw markdown_syntax.txt hosted with ❤ by GitHub

One of the cool things about Markdown is that it is widely supported. For example, if you’re using github (or gist), any file with a .md extension automagically gets rendered as Markdown, thus:

Markdown is normal text, with characters like asterisks around phrases for bold and underscores for emphasis.

Links are easy as are images:

You can do code blocks by indenting the code with a tab or four spaces:

SELECT 42
FROM FOO;

And many markdown interpreters support the ``` notation to surround a code block and will apply syntax highlighting as well

SELECT 42
FROM FOO;

view raw markdown_syntax.md hosted with ❤ by GitHub

How Do I Write Markdown? What Tools Do I Need?

Seriously. Well, emacs works great too.

Markdown is plain text. ANY plain text editor can be used to write Markdown. That’s why it’s so awesome - it is completely portable. TextWrangler, FoldingText, TextEdit, Notepad, Notepad++, Ultraedit… take your pick

There’s a comprehensive reference guide here that guides you through the syntax.

But, there are other tools that can make your Markdown life even better, such as previewers.

Markdown Previewers 🔗

The best of these by a mile on the Mac is Marked2. It gives you a nice rendering of any markdown document that you’re working on. Used with the El Capitan split-screen it’s pretty-near perfect way to write Markdown.

Marked2 can also export to DOCX, PDF, HTML, etc.

Other Useful Tools 🔗

Editorial is a good iOS Markdown editor & previewer
Mou does quite a good job of an all-in-one Markdown editor & previewer for the Mac. Personally, I prefer running two separate tools that excel at editing and previewing respectively, instead of one single one trying to do both. YMMV.
Emacs has a good markdown-mode

Ways to Generate Output from Markdown

Marked2 can also export to DOCX, PDF, HTML, etc.
pandoc can generate a huge range of output formats from markdown input.

Markdown geek-out

Rmd is a combination of R and Markdown. Pretty cool for writing reports with embedded R output.
When you get into the outer-reaches of Markdown, you’ll find that there are different “flavours”. There’s the original markdown, there’s github markdown, there’s Common Markdown. This only really matters when it comes to trying to do some funky formatting, and if the previewer/renderer that you’re using supports a different flavour. Some, like Marked2, will let you choose which to use.

Robin Moffatt

Robin Moffatt is a Principal DevEx Engineer at Decodable. He likes writing about himself in the third person, eating good breakfasts, and drinking good beer.