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.

  1. Grab my Markdown code from above, or write some of your own.
  2. Paste it into the text box at the top of Dingus.
  3. Click Convert.
  4. 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:

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.

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 24 September 2016, in open standards, technical writing and tagged , , , , . Bookmark the permalink. 15 Comments.

  1. 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

  2. There’s also AsciiDoc to consider, which offers the promise of having semantic markup as well.

  3. 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

  4. 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

  5. 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

  6. 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!

  7. 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

  1. Pingback: How to get started with Markdown and where to try it out | INFORMAZE

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: