How to get started with Markdown and where to try it out
Technical writers have heard quite a bit recently about Markdown. Putting aside the question of whether Markdown is the right choice for technical documentation, it’s interesting as a tech writer to know more about the language itself. What is Markdown, where can we see it in action, and how can we try it out? Here are some pointers. If you have any other tips or stories about Markdown, I’d love to hear them!
Markdown is a markup language designed for quick and easy creation of simple documents. The syntax is pared down to the minimum, with the result that:
The syntax is easy to remember.
A Markdown document is easy to read, since much of the content is free of markup tags.
Along with the markup syntax, Markdown comes with a parser (a piece of software) that converts the markup to HTML, so you can display the document on a web page.
Other well-known markup languages are HTML, XML, reStructuredText, various forms of wiki markup, and many others.
Example of Markdown
Here’s a chunk of the above text in Markdown format, with an added level 2 heading, “What is Markdown?”
## What is Markdown?
[Markdown](https://daringfireball.net/projects/m...) is a markup language
designed for quick and easy creation of simple documents. The syntax is pared
down to the minimum, with the result that:
* The syntax is easy to remember.
* A Markdown document is easy to read, since much of the content is free of
markup tags.
Along with the markup syntax, Markdown comes with a parser (a piece of software)
that converts the markup to HTML, so you can display the document on a web
page.
Equivalent in HTML
Here’s the same text in HTML:
What is Markdown?
Markdown is
a markup language designed for quick and easy creation of simple documents.
The syntax is pared down to the minimum, with the result that:
The syntax is easy to remember.
A Markdown document is easy to read, since much of the content is free of
markup tags.
Along with the markup syntax, Markdown comes with a parser (a piece of
software) that converts the markup to HTML, so you can display the
document on a web page.
Getting started with Markdown
When I first encountered Markdown, I already knew HTML and the wiki markup syntax used in Confluence. For me, the best approach to Markdown was:
First quickly scan the most basic syntax elements, to get an idea of the philosophy behind Markdown and to pick up the patterns. I’ve included some pointers below, to give you an idea of the patterns in the syntax. Note, though, that there are variations in Markdown syntax.
Then find a good cheatsheet and refer to it whenever you need to check up on something. Here’s a good cheatsheet.
If something doesn’t work, consult the full syntax guide.
Where can you try it out?
The best way to learn is to do.
Grab my Markdown code from above, or write some of your own.
Paste it into the text box at the top of Dingus.
Click Convert.
Scroll down the page to see first the HTML code and then the rendered version (HTML Preview) of your text.
Basic syntax
Here are those pointers I promised, to get you started.
Heading levels
# My level 1 heading
# Another level 1 heading
## My level 2 heading
### My level 3 heading
#### You get the drift
Paragraphs
No markup, just an empty line before and after each paragraph.
Links
Put the link text inside square brackets, followed by the URL in round brackets.
[Link text](https://my.site.net/path/)
Another way of doing links is to define a variable for the URL somewhere on the page, and use that variable instead of the URL in the text. This is useful if you need to use the same URL in more than one place in the document, or if you want to keep the messy, long URL away from the text.
[Markdown] is a markup language,
blah blah blah - this is the rest of my page.
[Markdown]: https://daringfireball.net/projects/m...
Bulleted list
* My list item
* Another list item
* A list item embedded within the previous one
* Another embedded item
* An item in the main list
There must be an empty line before and after each list, otherwise it gets mixed up with the preceding or following paragraph.
Numbered list
There are a few ways to do numbered lists. Here’s one:
1. My list item
1. Another list item
* An embedded bulleted list item
* Another embedded item
1. An item in the main list
You can mix and match bulleted and numbered lists, with varying degrees of success.
