HTML, which you should already be familiar with, stands for Hyper-Text Markup Language.

Markdown is a newer format which is gaining popularity across the web. It allows you to write plain text (with some basic conventions) which is programmatically converted into HTML.

This means you can quickly jot down your thoughts without having to worry quite so much about the final product.

Dialects and engines

Markdown was originally a specific program which converted Markdown files (*.md) into HTML. It has since been implemented by many different programmers in many different languages. Many of these implementations have their own quirks, some of which are nice, some of which are not.

Each of these dialects, or 'flavours' is a little different, and you have to know which engine you are writing for when you write your Markdown.

I've written the engine for this site in Javascript, which is especially nice because the code that runs on the server can also be expected to run on the client. As such, you can see the code for the Markdown parser I use here.

Benefits of Markdown

When you first visit a page on this blog, the server looks up the '*.md' file which corresponds to the url. It converts it to HTML, then swaps it into a template file. This is called 'serverside rendering'. It makes my life easy because I only have to write the layout once, and then I just generate content to fill it.

The process of converting and swapping is a little bit harder on the server than just serving pre-formatted html, though. For this reason, I wrote some code that makes the server's job a little bit easier by offloading some of the work onto the client (you).

The first page you visit contains links which tell your browser what assets are necessary to display the page. Any page might contain images, styling, or scripts. Browsers can be instructed to cache these assets, but if they aren't, each page reload causes the browser to fetch those assets all over again. By telling your browser to first download the markdown parser, I can avoid these reloads.

Clientside rendering

When you click a link, rather than browse away from the current page to the target page, this site instructs your browser to fetch the markdown content from the server. It then converts that markdown into HTML, and swaps it into the page itself.

To avoid redownloading that markdown content each time, I've made it so that the browser stores previously visited pages in its memory (as markdown, so as to minimize overhead).

This technique has many benefits:

  • It saves bandwidth by only shipping assets once
  • It improves your experience by loading new assets faster (since markdown is smaller than HTML)
  • It exposes the source text in a variety of formats

What formats?

The mechanism that allows your browser to download new content without reloading the page is called AJAX (Asynchronous Javascript And XML). Instead of serving XML (which is a lot like HTML, and similarly verbose) I serve .JSON files.

JSON stands for JavaScript Object Notation. It's compact, yet it describes the function of each piece of data transmitted within the object. You can see the JSON for this page here.

Visiting a plain URL causes the first page to be rendered serverside, and templated, as I mentioned above.

You can view the plain markdown source for any page by appending .md to its url, though, like this.

Finally, if you want to see that Markdown rendered, but not in a template, you can append .html to the url, like so.

You can see the code which handles this process in this server's github repo.

Markdown is not a handicap

You may have gotten the impression that since it's easier to write than HTML, Markdown may limit what you are able to write. If this were the case, I would not be using it. Markdown is actually a very expressive format, though you must keep in mind that not all Markdowns are created equal.

The best way to learn Markdown is to just start writing it. I made a single page Markdown editor which you can use, available here. The full source code for this parser is available on Github, or as an npm package.

Back to the point: Markdown provides a terse syntax for specifying the HTML elements most commonly used in prose. Its syntax is such that even if you don't render it into HTML, it should still convey a similar meaning.

When you want to write more than just prose, that is, when you want to format your page in a more advanced way, or apply styling, Markdown gets out of your way. You can always fall back to writing natural HTML, and when you do, it will be inserted into the rendered content as is. That means you can always write inline HTML when it's necessary, but save time by using the shorthand when it isn't.

Of course, this means that you can't write Markdown within HTML elements, since the parser will ignore all markdown within tags. That means you don't have a simple way of writing Markdown within a 'div' or 'span', you need to switch fully to writing HTML if that's what you require.

I work around this fact by writing one large piece of Markdown, and swapping it into an HTML template. This isn't quite as flexible, but for my purposes it's the most effective technique.

At it's best, Markdown is far more expressive than HTML, and at worst, it is HTML.

Actually writing Markdown

There are many possible use cases for Markdown, and the capacity for inline HTML and styling is not always desired. For something like a wiki, this would actually detract from the user's experience (unreadable styling errors), or security (malicious scripts). As such, there are many dialects which support only a subset of what I'll cover below.

This site is just my personal blog, so I can safely assume that none of the HTML I write will be malicious in nature.


You probably want to start any piece of writing with a title or heading. Most Markdown dialects use hash marks for titles. My particular engine allows multiple forms of the shorthand.

# This is a title #
# So is this

Which renders as:

This is a header

AKA an h1

To be more exact, those are h1 elements. For different header sizes, just include more hashes, h2 to h6 look like this:

## h2
### h3
#### h4
##### h5
###### h6

Which renders as:





Emphasis via bold or italic text

You probably want to be able to bold your text, or italicize it. Just like HTML, Markdown allows you to nest these two features either way.

**This is bold**

__So is this__

_this is italic_

*so is this*

**_This is bold and italic_**

_**So is this**_

__*and this*__

*__this too__*

This is bold

So is this

this is italic

so is this

This is bold and italic

So is this

and this

this too


This is definitely not as widely used as <strong> or <em> tags, but Markdown features a syntax for striking through text.

~~Because everybody loves tildes!~~

Numbered and bulleted lists

Like bolding and italicization, you have some flexibility when it comes to what characters you use.

* This is a list
* An unordered list, to be exact
  + You can use other characters
  + and indent
  + when you want nested lists
* Then continue the initial list
  1. You can even combine ordered lists
  2. Which don't necessarily even have to count in order
  1. Do this if you want
  0. You won't be able to tell the difference once rendered
* That means you can freely move elements around without having to rename them.
  • This is a list
  • An unordered list, to be exact
    • You can use other characters
    • and indent
    • when you want nested lists
  • Then continue the initial list
    1. You can even combine ordered lists
    2. Which don't necessarily even have to count in order
    3. Do this if you want
    4. You won't be able to tell the difference once rendered
  • That means you can freely move elements around without having to rename them.

Hypertext is built upon the expressive power of links. Markdown provides numerous shorthands to make writing links easier.

You can simply write in a complete url. If it is recognizable as such, the parser will render it as a proper link.



If you want to mask a url behind some text, as a regular anchor element in html would allow you to do, you can use the following notation:

[Displayed text](/markdown)

Displayed text

That works for local links, but if you want to link outside of your own site, you have to use the full URL:

[My clearnet website](http://transitiontech.ca)

My clearnet website

Escaping characters

You've seen that some characters have special meanings in Markdown. There may be situations when you want to display that character, and not format something according to its special meaning. In such cases you can precede it (or escape it) using a backslash ''.

For instance:

\# This is not a header
\[this is not a link](http://thoughThisWillRenderAsOne.com)

# This is not a header

[this is not a link](http://thoughThisWillRenderAsOne.com)

Code blocks

Lots of people like to blog about programming, but it tends to be a pain, since so many characters using in programming languages have meanings in html. You end up having to use special symbols or strings to represent characters like less-than '<', or greater-than signs '>'.

Markdown parsers are built to recognize the difference between these symbols when used as HTML and as parts of code. If it ever fails to parse your intended meaning, you can force literal behaviour using code blocks in one of two flavours (if you don't want to just escape the character).

`backticks used in pairs around text become inline code`

backticks used in pairs around text become inline code

Three backticks in a row indicate that the enclosed text is a preformatted code block.
A single token following the opening ticks can be used to indicate what kind of code it is.

Three backticks in a row indicate that the enclosed text is a preformatted code block.  
A single token following the opening ticks can be used to indicate what kind of code it is.  

Some parsers simply treat anything indented consistently with four spaces as being a code block.

This will be interpreted as code
So be mindful of your spacing.

You can also start consecutive lines with a > if you want to indicate the same thing.

Such that this is interpreted as being preformatted
and so is this
and this

Where spacing is significant

There are many situations where you may want to hard wrap some text, such as in editors that don't automatically wrap text around, or which wrap text without respecting word boundaries.

Lines written with no trailing spaces immediately before the line end, or without a blank line between them are treated as being one consistent phrase, and will be concatenated into a single <p> element when parsed.

You can break up text by placing two spaces at the end of the line
This is often problematic, though, as most editors will not display spaces.

It is generally better to split unrelated sentences with blank lines.

This is a good rule to follow if you want your unrendered Markdown to more accurately resemble your rendered Markdown.

Inline HTML

As I mentioned much earlier in the article, most flavours of Markdown allow you to mix in HTML with the rest of your writing. When your parser encounters HTML tags, it simply embeds it into its HTML output. That means that whenever you want to do something Markdown is otherwise incapable of, you fall back to strict HTML.

As such, you have the options of writing page-specific styling in your .md files, which would look like this:


<div class="blackOnRed">
### This isn't Markdown

## Now we can write Markdown
### This isn't Markdown

Now we can write Markdown

Note that Markdown content inserted within HTML tags will not be treated as Markdown. It will be inserted as is.

In conclusion

Markdown can increase not only your own productivity by reducing the time it takes to write HTML, it can help your server by reducing the amount of bandwidth used when transmitting content.

Spend some time playing with it, and see if it suits your creative process!