Markdown is a plain text format for writing structured documents. Writing Markdown is a great way to take notes, the author spends less time distracted by formatting and more time focusing on content.

To get started with Markdown create a plain text file. Markdown documents are identified with the file extension ‘.md’, so if your new file ends with ‘.txt’, change it to ‘.md’.

Markdown files can be edited with any text editor. Apps such as Notepad or Wordpad are suitable. Text editor apps won’t help you though while editing your Markdown files. The light-weight IDE, VSCode has built-in support for Markdown, without the need to install extensions.

The original specification of Markdown , by John Gruber and Aaron Swartz, dates from 2004. The specification has been interpreted differently since then, leading to many implementations. There are now many variations of Markdown.

CommonMark

The CommonMark project describes itself as being “A strongly defined, highly compatible specification of Markdown”. Multiple applications and frameworks now work to the CommonMark specification. CommonMark is also the stated direction of GitHub and is the specification used by VSCode .

Markdown Tutorial

Here’s an example of a Markdown document:

 1# This is a Level 1 Heading
 2
 3This is plan text. Here is a word in **bold**. An example of *italic*.
 4
 5## A Level 2 Heading
 6Some text here with a link to [this site](https://example.com).
 7
 8### A Level 3 Heading
 9
10Numbered lists are supported:
11
121. this is the first item
131. here's the second
141. and the third
15
16Tables are also supported:
17
18| Animal | Sound |
19|--------|-------|
20| Dog    | woof  |
21| Cow    | moo   |

Code Blocks and Syntax Highlighting

Code blocks begin and end with three backticks, like this:

` ` `

` ` `

To add syntax highlighting, include the name of the language at the start of the code block, such as:

` ` ` Rust

` ` `

Online Tutorial

The 60 Second Tutorial is a great place to start.

Resources of Interest

  1. highlight.js for a list of languages available to add to code blocks.
  2. Tables Generator is a fast way of creating tables and supports pasting data copied from spreadsheets, docs and other sources.
  3. VSCode is free, open source and widely used. Great for editing Markdown, also languages such as Python, Rust, C++. The preview pane provides instant feedback on how your document looks. Shortcut to enable preview: Ctrl + K V.
  4. Code Spell Checker , extension for VSCode, is a general spell checker. Great for spell checking source code comments and Markdown documents.
  5. Markdown PDF , extension for VSCode, generates PDF and HTML versions of the currently edited Markdown file.
  6. Pandoc is a super powerful open-source utility that converts docs in various formats to many other formats. Excellent for converting Markdown to .epub format, .docx and many other formats.