Markdown makes it easy to write formatted text quickly. It’s a plain text format that uses basic notations to add semantics to the document. The format is widely adopted, it is a very simple and efficient tool in the hands of a developer.

It’s common to write the documentation in markdown format, then generate static websites/pages from it.

Most developers like it because the modifications can be tracked in version control systems, and does not need a special editor.

Basic syntax

The markdown document translates to simple HTML.

For example, if the line starts with # Heading it will be converted to <h1>Heading</h1> upon viewing.

Here are the minimal syntax that every developer needs to know:

<!-- Commented text -->

<!-- Headings -->
# h1 heading
## H2 heading
### H3 heading
#### H4 heading
##### H5 heading

<!-- Paragraphs -->
One empty line creates a new paragraph.
This line starts in a new line but still in the same paragraph.

This is a separate paragraph

<!-- Unordered List -->
- item 1
  - nested list
- item 2
- item 3

<!-- Ordered List -->
1. item 1
   1. nested list
1. item 2
1. item 3

<!-- Horizontal Divider Line -->
---

<!-- Link -->
[alt text](./anchor/href/url)
<!-- Image -->
![embedded image alt text](./embedded/image/path)

<!-- Text Format -->
*italic*
**bold**
~~strike through~~

<!-- Quote -->
> multi line
> quoted text

<!-- Embedded code -->
monospace code: `here`

```bash
#!/bin/bash
# this is a bash highlighter fenced code block
pwd
```
<!-- Table -->
table col 1 | table col 2 | table col 3
--- | --- | ---
row 11 | row 12 | row 13
row 21 | row 22 | row 23
row 31 | row 31 | row 33

Converters

Markdown is widely supported on the web:

  • many applications let you write formatted text in markdown.
  • README.md files in the projects are converted and viewable on the site for example in github, gitlab and npm.
  • some messaging apps let you format messages in markdown syntax
  • static site generators create HTML pages from markdown documents

Most of the time you don’t need to worry about converting them. However, you have the option to add markdown support to your website. You can also convert them to other formats, like pdf or latex.

Pandoc

Pandoc is the swiss army knife of converting between markup formats.

My favorite part is that it can export my doc to pdf.

pandoc README.md --pdf-engine=xelatex -o documentation.pdf

Markdown-it

Markdown-it provides a simple way to render markdown text into a webpage in javascript.

Different flavors

When I started to learn markdown, the most confusing part for me was that the format has different implementations, and they come with different extensions. As I later found out the initial description of Markdown contained ambiguities and unanswered questions, so the implementations that appeared over the years have subtle differences and many come with syntax extensions.

CommonMark comes to the rescue and provides a consistent way to write markdown. If the parser you use support it, you can be sure that it works as expected.

Github adds extra features on CommonMark, like emojis and marks for task completion.

Styleguide

The style and syntax are not enforced, if the document has an error, it will be converted anyway, only the result will most likely not look as intended.

I recommend you to use a linter, like markdownlint to keep your markdown files consistent. Markdownlint has many rules, that points out errors and warns you about coding style best practices.

Happy coding!