What is Markdown?

Markdown is a markup laguage designed to be lightweight and human-readable. Originally it was conceived as a tool to export plain text to HTML, but ever since its inception in 2004 it has been expanded not only to include additional functions, but additional markup languages.

Why would I use it?

In general, it provides an easy way to insert some kind of formatting to your text, with the added advantages of:

1. Never taking your hands off the keyboard,
2. Being easy for humans to read,
3. Being easy for machines to translate and understand.

Is it easy to use?

A lot! Its tenets can be learned in minutes and are presented here:

Headings

A 1st level heading is a line of text followed by a line of "equal" signs. A 2nd level heading is followed by a line of single dashes.

It can also be used and extended all the way to h6 by preceding a single line with however many pound signs you need. Thus, the line

### An h3 heading

Will be an actual h3 heading. Note that the pound signs do not need to be matched at the end like MediaWiki does, but it can be done.

Text attributes

Bold can be expressed with either double asterisks or double underscores.

Italics is the same, but with single asterisk or underscore

Monospace uses backticks. This also escapes formatting inside of the backticks.

Lists

Lists can be either:

1. Ordered (like this one), or
2. Unordered

A list is created with succesive lines of list markers:

• Ordered lists are preceded by a number, a single period and a space
  • Curiously, it doesn’t have to match the actual item index
  • Meaning, you can create a list in which all lines are preceded by ‘1.’ and will still count as an ordered list
• Unordered lists can be preceded by either a single dash, a single asterisk or a ‘plus’ sign.
  • Ideally, you use the same marker in a single list to avoid confusion
  • Lists can also be nested

Other

Blockquotes borrow the ages-old email format:

Four score and twenty years ago…

You can define links several ways:

1. The link text surrounded by brackets immediately followed by the link address enclosed in parenthesis, like this: [Everything2](https://everything2.com) produces Everything2
2. A much cleaner way is to just enclose your text with brackets and later in the document (usually at the end) to define its address, like this: [Wikipedia] and at the end of the document having a single line with [Wikipedia]: https://en.wikipedia.org will produce a valid link as well: Wikipedia
3. If you don’t mind your link text being the same as the actual address, you can just enclose the address as if it were an HTML tag: <https://random.org> will produce https://random.org

You can insert images almost the same as if they were links. The following line will be translated to <img alt="Alt text" title="title attribute" src="your_image.png" />


You can define code blocks by starting your paragraphs with four spaces or 1 tab:

import math
squares = [i**2 for i in range(10)]
sines = [math.sin(x) for x in squares]

You can define a horizontal rule with a line having only three dashes (with blank lines above and below so as not to confuse them with level 1 headings).

The full syntax with all its nuances can be found at https://daringfireball.net/projects/markdown/syntax

Disadvantages

Markdown was conceived to deal with only one output format and even then only its most basic functions, as seen above. There’s a lot of functions that are not present out of the box:

• definition lists,
• elements with id or class attributes,
• tables,
• footnotes,
• abbreviations,
• code blocks

Moreover, the simplicity of this language also attracted many a hacker to create a tool that could take a valid Markdown document and spit out its analog on many other formats, only to find many other functions lacking. This author, for instance, wanted:

• cross-references within the document,
• an easy way of dealing with academic citations,
• anchor links to all headings,
• an easy way to print out source code with appropriate syntax highlighting,

Not to mention that, due to the E2 syntax, all external links have to be manually adjusted, from an <a> tag to the appropriate bracket link.

However, many of these limitations can be overcome with one or more variants of Markdown. Among the largest/better known are:

• GitHub flavored Markdown,
• MultiMarkdown,
• CommonMark,
• Pandoc and its Pandoc-flavored Markdown, champion of all variants to this author and the subject of another node.

Source Markdown for this document can be found at this public draft. Please note that the conversion of this source will produce valid HTML, but due to the way E2 handles links, all 'a' tags will be manually adjusted to its appropriate pipe link format to produce the document you're looking at right now.