Have you ever looked at documentation, a coding blog post, or visited a github repository? Then you have almost certainly looked at Markdown (or the end product of Markdown). As a developer it’s always great to know how to write in Markdown, so here’s a quick and dirty cheatsheet to make your life easier!
What is Markdown and why should I use it?
Markdown was created in the early 2000s as an easy tool for people writing on the web. Essentially the text you write in Markdown syntax is converted by the platform you are writing on (actually, it’s perl at work), into HTML.
The idea behind Markdown is to make it as easy as possible to write plain text in an easy to read format. You should be able to read something written in Markdown syntax in both its converted and non-converted forms!
Because of this, Markdown is ideal for writing documentation. If looking at the documentation on a text editor, the file will be unconverted, but still very readable. If looking at the documentation on a platform like Github, the document will be converted into good looking HTML! If you are building anysort of application, program, or website you almost certainly will want to write some sort of documenation. While there is technically no right or wrong way to do so, you will likely want to use something like Markdown to achieve this. While writing your Markdown, try using a tool like StackEdit, which will show you your plain text on the left, and converted Markdown on the right! (Atom text editor also has a markdown previewer out of the box.)
Quick guide to Markdown:
I’ll show you the Markdown syntax in plain text first, then more or less what the conversion looks like.
Headers
First things first, you’ll want to know how to create your basic HTML headers!
Also… Only for an H1 and H2, you can write it in an underline style
Underline H1
======
Underline H2
------H1
H2
H3
H4
H5
H6
H1 and H2 in underline style:
Underline H1
Underline H2
Basic Formatting
Italics are denoted with asterisks or underscores.
Bold is denoted with double asterisks or underscores.
If you want to combine the two, you simply use both double asterisks and single underscores.
or… double underscores and single asterisks.
You can implement strikethroughs using the doulbe tilde The symbol above tab.
Lists
- An ordered list is denoted like so:
- Using numbers like this
- And this
- It’s funny, because the actual number doesn’t matter, just that it’s a number (it could be all ones).
- This is an ordered sublist, denoted by at least one indented space
- And another one (DJ Khaled).
- An Unordered sub-list, again, indented spaces (at least one)
This is an indented paragraph whithin a list item. The blank line above is important, as well as the leading spaces.
You can also do this, to have a line break without a whole new paragraph. Here, you need to have trailing spaces however.
This is a separate line, but in the same paragraph as the line above.
- Unordered list can use:
- asterisks
- pluses
- dashes
Links
Markdown supports linking in two ways: inline and reference. Both are denoted with square brackets.
For easy linking without anchor text, you can simply use URLs and URLs in angle brackets like: http://techtalentsouth.com or http://techtalentsouth.com and sometimes techtalentsouth.com depending on the platform. (i.e. github does not allow this).
For other links we use inline style:
Inline-style but to a relative(internal) path
or we could use reference style:
You can use numbers for reference link ids
Reference style allows you to “refer” to a link that is defined elsewhere in the document using a custom id, like below:
You can also create a link just using the link id itself
Images
Images likewise operate much like links. The also use square brackets and make use of inline and reference syntax.
Here’s the TTS logo:
Inline: 
Reference:
Code and Syntax Highlighting
Since markdown is often used for documentation, code blocks are a widely used feature built into github. However… it is important to remember that syntax highlighting is not built into markdown. Syntax highlighting is determined by the platform in which the markdown file is being displayed on. i.e. Github or rubygems.org. Depending on the platform, the language you are writing about may or may not be supported.
You can write code in two ways:
You can show small snippets of code inline by usings single backticks.
or you can write entire blocks of code boxing in your code with three backticks ```
for syntax support simply denote the language after the first set of backticks.
Block Quotes
In documentation, block quotes are incredibly helpful in pulling out specific/important information and giving it a little extra emphasis.
You can use old-school email block quote syntax. Where each line. Can be denoted with a new angle bracket. But they are all apart of the same quote.
You must have some text in between quotes, otherwise they will all run together.
In markdown, however you only need to put an angle bracket at the beginning of a paragraph that you have handwrapped. Like this one here. In addition:
you can inception your block quotes and add other types of markdown.
Inline HTML
Since Markdown essentially transposes to HTML, you are also able to write pure HTML in your markdown document.
| HTML Table | |
|---|---|
| you can | basically write |
| any html | you want |
| **markdown doesn’t work though** | use HTML |
You can even include an iframe this way:
Other formatting
You can also include horizontal rules and line breaks in markdown.
For horizontal rules you need three or more…
Hyphens
Asterisks
Underscores
For line breaks, one return like this one creates a new line, but keeps it in the same paragraph. For a new paragraph, you must hit return twice
like so.
That’s a wrap
As far as Markdown goes, that’s a wrap! As a developer, I highly encourage you to start writing documentation in Markdown. Like all coding syntax, it may take you a little time to get the hang of it, but once you do, you’ll be writing great-looking doucmentation in lightning speed!
