Markup vs Markdown - what's the difference?

Markup vs Markdown - what's the difference?


5 min read

Since day one of learning to code, we're taught that HTML stands for "Hypertext Markup Language". MDN defines HTML as "...the code that is used to structure a web page and its content." Fair enough.

I, on the other hand, recently explained HTML way less formally: a Tweet asked the following: "Without using the words Code, Programming, Markup, Language, can you explain what HTML is?".

My answer to that? Well, prepare to have your mind blown:

mind blown gif.gif

"If a website was a tent, HTML would be it's frame."

Seriously, I actually wrote that. Out there, on the web, for all the world to see (with the typo in 'its' as well ๐Ÿ™„*)*. Meh, it's true and I stand by it. I'm trying to teach my tween children to code, so am used to coming up with nice basic explanations for these things.

Most of us are very familiar with HTML and its series of elements. For those just getting started on this journey, I highly recommend reading the MDN page linked in the very first paragraph of this post. Does that sound like a lot of scrolling? It does, doesn't it? Well, I got you fam - here's the link again: MDN - HTML basics

I'll be honest - it's one of those definitions that I heard a few times and filed in the back of my mind along with other random trivia such as

  • & (ampersand) means 'and'; and

  • the unicorn is the national animal of Scotland (I swear, it's true!).

Good to know, but I digress...

So, what is a "Markup Language"?

Formally, a markup language is "a notation used to annotate a document's content to give information regarding the structure of the text or instructions for how it is to be displayed". Cool. Rather self-explanatory, I feel.

So, when I recently started blogging here on Hashnode and cross-posting on DEV Community, I was introduced to the term, and concept of, "Markdown".

Markdown is basically the method of writing posts on these platforms using shorthand annotations to format the text using inline syntax. Examples include:

  • Using hash (#) symbols to indicate header text by placing a single hash symbol (#) and a space before the words that you'd like to have appear formatted as Header 1 text. Two hash symbols for Header 2 text, and so on. # This is Heading 1, whilst ## This is Heading 2.

    • (Thanks to John for letting me know about an error in my original version of this post - I'd been under the impression that one needed the hash symbol both before AND after the text. Turns out that's not the case.)
  • Embedding a link, as I've done a few times in this post, in text by using square brackets [] around the words to be hyperlinked and immediately adding the relevant URL after with regular () brackets around it, shown here: [I'm an inline link](put-link-here).

I decided to find out.

The above examples and explanations, whilst undoubtedly fascinating (๐Ÿ™„) still, however, don't explain the DIFFERENCE between the two - markup vs markdown. So far, I've merely defined the two.

Well, markUP is, as written above, "a notation used to annotate a document's content to give information regarding the structure of the text or instructions for how it is to be displayed". In summary, it's a general umbrella term for notation on how to display text.


MarkDOWN is "...two things: (1) a plain text formatting syntax; and (2) a software tool, written in Perl, that converts the plain text formatting to HTML." - reference. Additionally, Markdown is a lightweight markup language for creating formatted text using a plain-text editor. Created in 2004, it is widely used in blogging, instant messaging, online forums, collaborative software, documentation pages, and readme files.

Got that? MarkDOWN is a markUP language.

And there you have it.



Want to become a markdown expert, so accomplished in the syntax that we common folk bow in your presence, all the while begging for your autograph? Of course you do! Check out the Markdown Guide at The site includes a handy getting started section, basic syntax page, extended syntax page, cheat sheet, etc.

It took me a REALLY long time to get there, didn't it? It's like one of those recipe websites where we first need to hear the author's life story about returning to the farm as a child before getting to the ingredients list on page four!

Once you're done nodding vigorously in agreement with the previous sentence, please stop by on Twitter to say Hi! No really, please do. I've got hardly any Twitter followers so am currently Tweeting into the void. It's all rather sad...

Until the next time!


Sidenote 1: Any glaring errors and omissions? Am I talking out of my ...? Itโ€™s possible, nay, probable (according to my dear wife), given my relative newbie-ness to coding. Feel free to comment / advise / correct / praise / troll accordingly, as appropriate, and Iโ€™ll update this post as required.

Sidenote 2: See the logos in the cover image? The markdown logo is legit. The markup logo, however, is not. I couldn't seem to find a standard markup logo, probably because it's a far more general / generic term, so I made this one, with the arrow pointing up, myself.