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/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.
Equivalent in HTML
Here’s the same text in HTML:
<h2>What is Markdown?</h2> <p><a href="https://daringfireball.net/projects/markdown/">Markdown</a> 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:</p> <ul> <li>The syntax is easy to remember.</li> <li>A Markdown document is easy to read, since much of the content is free of markup tags.</li> </ul> <p>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.</p>
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/markdown/
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. 🙂
More markup
There’s plenty more you can do with Markdown, and there are a couple of syntax varieties to trap the unwary. For example, GitHub has a special flavour of Markdown.
Recent articles about Markdown
There’s been a fair bit of discussion about the pros and cons of Markdown recently. Here are a few of them:
- Eric Holscher wrote a popular and much commented post in March this year: Why You Shouldn’t Use “Markdown” for Documentation. Congrats Eric, this is a really great example of in depth analysis and reasoned opinion. It also sparked a large amount of impassioned conversation, which is still going on in forums around the world.
- Tom Johnson has a section on Markdown in his course on documenting REST APIS: More about Markdown.
- Victor Zverovich compares Markdown and reStructuredText: reStructuredText vs Markdown for documentation.
- Ben Cotton comparesMarkdown, reStructuredText, DocBook and LaTeX: Markup lowdown: 4 markup languages every team should know.
My opinion
In my day job, I write docs in both HTML and Markdown. I prefer HTML for comprehensive technical documentation. Markdown is good for very simple documents, but the syntax becomes clumsy for more complex things like tables, anchors, and even images. On the other hand, there are excellent benefits to using Markdown for quick collaboration on a document.
As is so often true, we need to choose the best tool for each use case. It’s a good idea to get to know Markdown, so that you can form an opinion and be able to use it when you need it.
Posted on 24 September 2016, in open standards, technical writing and tagged Markdown, markup, technical communication, technical documentation, technical writing. Bookmark the permalink. 16 Comments.
kramdown Markdown is a bit more powerful than regular Markdown. You can add custom classes to elements, add ID tags to headers, and even add a “markdown=”1” attribute to HTML elements to use Markdown in those HTML elements.
I also use image templates, managed links, and alert templates in Jekyll to take care of the other syntax needs.
Hallo Tom
Thanks! Adding CSS classes and header IDs are extremely useful add-ons. The header IDs make it possible to include anchors in links, so that you can link to a particular section of the page without having to resort to an HTML <a> tag. And being able to include Markdown in an HTML element is also super useful. That means you can use HTML for complex page elements (such as tables) but still have the easy-to-read Markdown within them.
Cheers
Sarah
There’s also AsciiDoc to consider, which offers the promise of having semantic markup as well.
Hallo Ellis
That’s a good addition. I’ve never used AsciiDoc, or reStructuredText for that matter. So many good things out there!
Cheers
Sarah
Great post, Sarah. I chose Haroopad for assembling release notes. My product management team can use it to compose content and we can automatically insert issue descriptions from jira automatically. It’s cross-platform (Windows+Mac), has a WYSIWIG interface, supports complex table formatting, outputs HTML and PDF, and supports the markdown format that’s compatible with the custom WebCMS I’ve started building.
Hallo Steve
Haroopad looks pretty cool. I’m also intrigued by the button labelled “Developer (coming soon)” – expect more integrations when they open up an API!
Cheers
Sarah
Hi Sarah,
I’m excited to see so many people adopting Markdown. I know it has limitations for documentation, but I’m still a big fan of it.
The most exciting application of Markdown I’ve seen in a while is a new app called Marp (https://yhatt.github.io/marp/) that allows you to create presentations completely in Markdown. It’s especially great for people like me who like to start with an outline and build from there.
Hallo Leon
Marp looks awesome. Thanks, I hadn’t heard of that before. It’s an advantage when you can use the technology you’re accustomed to, when creating presentations. And docs, for that matter. No learning curve required just to be able to add content.
Cheers
Sarah
In my opinion, the strength of Markdown is its simplicity and unobtrusiveness in the kinds of documents it was designed for. It’s the perfect markup for short, un- or semi-structured documents like blog posts, comments, and other brief online communication. I use Markdown almost exclusively for professional communication so I can work offline in a text editor without the distractions of heavy formatting.
Much like its sibling wiki markup, though, the more “capable” you try to make the markup by extending it and adding new features, the more you undermine the simplicity that was the whole point of it existing in the first place!
Everyone has their own complexity threshold, but for me, “github flavoured markdown” is the most weight the syntax can bear.
Hallo Charles
That’s an interesting viewpoint. I think you’re right in that it comes down to the use case: Markdown works for simple docs. The issue arises when you’ve opted to use Markdown, and your requirements later expand.
Of course, you can usually insert HTML into a mostly-Markdown doc, to handle those pesky formatting challenges. But then you end up with a hybrid that, depending on the amount of HTML, clobbers the easy legibility of Markdown.
Where I work at the moment, we can choose to write the docs in either Markdown or HTML – the publication engine handles them both. That works well. Every now and then I find myself swapping a doc from Markdown to HTML when changed content requirements result in a more doc.
Cheers
Sarah
Hello, Sarah!
As always, you are so good at explaining things – I am going to re-post your article for our community, as an excellent reference 🙂
Checkvist also supports Markdown, but of course, with keyboard shortcuts 🙂 My favourite is ‘mh’ – if you press it on a list item, it becomes a heading, the level is calculated automatically. And of course, the ubiquitous Ctlr-b, Ctrl-i, and Ctrl-K for hyperlinks.
Don’t know whether you still use Checkvist for outlining, if you do would be great you checked out it with Markdown as well 🙂
Thanks again for the post – and thanks to all who commented for references to many interesting tools!
Hallo sasha
It’s cool to see how Markdown is integrated with various tools and workflows. Thanks for letting us know about its support in Checkvist!
Cheers
Sarah
Hi Sarah,
Above, you say above “Where I work at the moment, we can choose to write the docs in either Markdown or HTML – the publication engine handles them both”. I’d love to know what publication engine you use. It sounds exactly like what we are looking for at present. 🙂
I too love the simplicity of Markdown, but we have some quite complex single-sourcing needs, and some complex content too, so it would be perfect to have the choice of using Markdown or HTML. We’re tending towards a Markdown-based solution, and I’m getting concerned about how complex it will need to be. As Charles says above, I suspect some of our Markdown will be so complex that we will undermine the advantages of the simplicity which caused us to choose it in the first place.
Thanks for a very informative and timely post!
Hallo titch990
That’s a good question. We use a proprietary, internal tool to process the Markdown and HTML and push it to the website. So I don’t have any experience in developing that side of the process.
The Markdown package includes a piece of software that converts the Markdown to HTML. A good place to ask your questions about customising and extending the tool may be the Markdown discussion list. I’d be interested to hear what people have to say about this aspect of using Markdown too.
There are a few online (hosted) tools where you can host your documentation, including Corilla and Read the Docs. I see that the latter has just started a business option, where people will be able to keep their hosted docs private. That feature is still in beta, at this point.
Cheers
Sarah
Pingback: How to get started with Markdown and where to try it out | INFORMAZE
Pingback: Pros and Cons of Using Markdown for Technical Writing - Coiner Blog