Authoring Markdown - What, Why, How

Monday, September 15, 2014 4:57 PM

This is by far nothing new… Markdown has been around for quite some time. The reason I’m writing this is I’ve had a few friends who ask how I deal with it as it is new to quite a few people. So I won’t explain what it is in depth or the syntax. Instead, check out these links on it:

I’m not going to dip my toes in the recent debate kicked off by a few thought leaders who pitched Standard Markdown / Common Markdown. If you want to have that debate, leave a comment on this post and I’ll jump in. I want to keep the body of this on-topic.

Let’s jump in and answer a few questions: what is it, why would you use it and how I use / write it.

What is Markdown?

Think of it as HTML shorthand. You can write really fast without needing the mouse or reading with angle brackets. Headings are prefixed with a hash symbol… the number of hash symbols indicates the heading level. Want to make something bold? Surround it with two asterisks. Italic? surround with single asterisks. Code inline? surround with a single back tick. A code block (aka: fenced code block?), put four back ticks on a line before the code & on a line after the code. Some systems like GitHub even let you put the name of the language of the code for some slick color formatting.

Why do I use Markdown?

Quite simply, I can write HTML faster using it than writing HTML. I like how I can use it to write documentation within my projects in GitHub and it’s automatically rendered in the browser like this project I recently published for Microsoft: OfficeDev - Research Project Code Sample.

I also use it for writing my blog posts… I write in markdown, convert it to HTML and then post it to my blog. My blog engine, OrchardCMS, supports authoring in markdown, but I haven’t tested what happens my existing HTML based posts. I also recently started using it to author presentations instead of using PowerPoint… so far, love it! Here’s an example from a recent session I delivered:

How do I, & What do I Use to, Write Markdown?

Now to the meat of the post. This falls into two different categories: how to write it & how to view rendered it.

I use the text editor Sublime Text because it’s very extensible, has no toolbar of buttons & is quite heavy on controlling it via the keyboard. The Sublime website has a good overview on it. If you have a Pluralsight subscription, check out this course on Sublime: Sublime Text 3 from Scratch. There’s even a little, and extensible, build engine. Check out a few of these posts to get an idea what you can do:

The first package (Sublime’s extension framework) I install is called Package Control. Think of this like NuGet (for you Visual Studio folk) or NPM (for you NodeJS folk).

Here are the other packages I installed, as they relate to markdown authoring and why:

  • MarkdownEditing: Quite simply, this makes it easier to write markdown.
  • Markdown Preview: This lets you convert the whole file, or just what you have selected, to HTML and loads it in a browser to preview it. The other option is to just build it to HTML and copies it to the clipboard.
  • LiveReload: You can convert the the Markdown Preview package to actually build the markdown file to an HTML file. Then, with LiveReload (you need the $10 paid version along with this package & the free browser extension), when you build the file, it will automatically refresh the browser so you can see your changes almost immediately. It’s not just the markdown, it’s also the images or any CSS you might be referencing. Here’s a post explaining the whole thing: Sublime Text 3, Markdown & LiveReload.

I could explain how you can do it, but video is better. Here’s a quick video I did of me creating a very simple HTML fragment for using Sublime. I used the menu at first but then switched to the way I normally do it: all keyboard. I’m hitting the shortcut to build the markdown file which you can see from the built window at the bottom. Once the HTML file is updated, you see the browser refresh which is being controlled by LiveReload… it’s watching the folder for updates:

comments powered by Disqus