Learning web development: Markdown

This blog post is part of the series “Learning web development” – which teaches people who have never programmed how to create web apps with JavaScript.

To download the projects, go to the GitHub repository learning-web-dev-code and follow the instructions there.

I’m interested in feedback! If there is something you don’t understand, please write a comment at the end of this page.

In this chapter, we explore Markdown, a lightweight markup language that’s easy to learn and used a lot when writing about programming: documentation, comments, etc. We’ll need it in the next chapter. Learning it may seem like a detour but it’s easy to pick up and you’ll come across it often if you are interested in web development.

What is Markdown?  #

Markdown was created in 2004 by John Gruber. The motivation behind creating it was as follows.

Markup languages (languages for marking up text) use plain text and characters they treat as special to describe text that is not just a sequence of characters but has structure: paragraphs, bullet lists, headings, etc. HTML is a markup language. Two of its special characters are < and >.

Two benefits of markup languages are:

• They are less finicky than most word processors.
• Because content is stored as plain text, it’s easy to manage it via version control systems such as Git (see next chapter). That gives us unlimited undo, easy collaboration with others, and more.

However, especially HTML is also slightly unpleasant to write and read – unless shown in a web browser. Therefore, Gruber wanted to create a markup language that already looks good in plain text. It was inspired by how early emails were written – e.g., for quoting the text of another email, email apps support the following syntax – which is also used by Markdown:

> Your immediate attention is required!

This is what Markdown looks like:

## Heading

One paragraph with **bold** text.

Another paragraph with text.

* Bullet list
* Second item

Conveniently, if we open a Markdown file in a code editor such as Visual Studio Code, we’ll get syntax highlighting: The heading is displayed more prominently, **bold** is displayed as bold text, etc. That makes Markdown even easier to read.

Filename extension and media type of Markdown  #

• Filename extension of Markdown files: .md
• Media type of Markdown: text/markdown

An overview of Markdown  #

Paragraphs and line breaks:

Paragraph 1, line 1\
Paragraph 1, Line 2

Paragraph 2

Code block (<pre>):

```js
const add = (x, y) => x + y;
```

The js after the three backticks is optional and specifies which kind of syntax highlighting to use. Due to js, the previous text will be highlighted (e.g.) like this:

const add = (x, y) => x + y;

Further reading  #

• Blog post from 2004 by John Gruber that introduces Markdown

• CommonMark is a standard for Markdown. Its website also provides useful resources for learning it:

  • Markdown reference
  • Online “dingus” for trying out Markdown

• Pandoc is a tool for converting Markdown (and other markup language) to and from various formats: HTML, Word documents, PDF, EPUB, etc.