Getting started with Markdown

Posted on By Mark Wilson
This content is 4 years old. I don't routinely update old blog posts as they are only intended to represent a view at a particular point in time. Please be warned that the information here may be out of date.

The problem

One of my recent projects has been to build out a repository of architecture artefacts for my team to use in delivery of our engagements. I wanted something quick, simple to use, and my budget was… zero. I probably could have used Github or Azure DevOps but I wanted to integrate with an existing SharePoint site, so I simply created a new document library and started uploading files.

Some more requirements

I didn’t want a folder structure – ideally I will use the metadata on the files to allow searching – but I did want some simple release notes to act as an entry point/index of what’s here.

I wanted to avoid Office file formats. They are good for many things, but I wanted something lightweight that would render easily in a browser or a text editor. And I wanted something a bit more than a text file. Which led me to Markdown – something I’ve been meaning to get to grips with for a while now*.

A solution

Markdown is not new, but it is beautifully simple. And in a world of wall-to-wall Microsoft productivity tools, it turned out to be incredibly elegant.

Getting started with Markdown is simple. Open a text editor and write some words – as set out in John Gruber’s original post. This guide tells a bit more though – or try a tutorial.

I actually started writing my Markdown (.md) files with the Dillinger Markdown Editor. Once I had the basics, I switched to editing in the SharePoint text file editor, or in Visual Studio Code:

As can be seen from the screenshot in the tweet above, the syntax is pretty straightforward but I just use Adam Pritchard’s Markdown cheatsheet to help with any syntax stuff I can’t remember. And the Markdown files render pretty well in Edge (presumably in other modern browsers too). There’s no need to worry about special tools to render to HTML.

Markdown FTW

So that’s got me started with using Markdown. The learning curve is so gentle that I can’t see me using anything more heavyweight now (like a Teams Wiki or a shared OneNote) when a few .md files will do the job quite nicely…

* I have a dream. A dream that one day, we will no longer write our design documents in Microsoft Word but will select sections of standard text from a website, enter the design decisions in a form, and hit “generate”. Documents will be created for Consultants, rather than by Consultants – and I can avoid what sometimes feels like a life of constant copy-editing (good techies that can write well seem to be a rare breed). That day is still a long way away… or is at least a side project that I haven’t worked out how to get started on…