Markdown Tutorial

Markdown is a markup language similar to HTML or LaTeX, that specifies the formatting of a document. It is not as extensive or precise as either of the previously mentioned specifications, but the thing that makes it so attractive is that the "source code" is nearly as readable and sensible looking as the output. Markdown was patterned off of customs that have emerged from the world of email, to figure out what people natively do to convey styling when forced to write in plain text. These email inspired traditions were formalized into the definition of a language that is easy to write and easy to read. Markdown text is very versatile and can be translated into a variety of other languages, such as the aforementioned HTML or LaTeX. While Markdown cannot handle all cases that these other languages can, it does a great job at specifying the actual body of a document, and does so in a manner that is incredibly easy to learn and work with.

Note: there are different "flavors" of Markdown, and it is Github Flavored Markdown that will be discussed here.

Headings

Headings in Markdown are very simple. To make a first level (top level) heading, simply prefix the text of the heading with a pound and a space. For a second level heading, use two pounds and a space, third level, three pounds and a space, and so on for the others. This makes it very easy to make titles, subtitles, sub-subtitles, and so on.

An example of a document structure using headings might be something like the following:

# A First Level Heading

A brief introduction to the document.

## A Second Level Heading

Some text in the body of the document.

### A Third Level Heading

More Text in the document.

Paragraphs

Paragraphs are the main space where text lives in a document. Thankfully, in Markdown any piece of text that is not identified as a different type of element becomes a paragraph by default. It is normal to have newlines inside paragraphs because many text editors do not word-wrap, but anywhere with two consecutive newlines is considered the beginning of a new paragraph. For example:

This is a paragraph. It has
newlines within it, but is
still considered to be one
cohesive unit.

This is a separate paragraph.

Images

Images in Markdown are nearly identical to links. To place an image in a page, simply type an exclamation point, then a description of the image in square brackets, followed by the URL of the image in parenthesis, as follows:

![A micro-scale BYU logo made of carbon nanotubes](http://nano.byu.edu/images/cnt_cougar.jpg)

The text description of the image is called the alt text, and is very important. This text one of the large factors that search engines use to identify the image. Also, in the event that a browser cannot or will not load the image quickly or at all (think of a mobile browser with a slow connection), the alt text will be displayed instead of the image. Screen readers also read the alt text, so people using accessibility settings rely on it.

Lists

Lists in Markdown are just what you would expect them to be. To form a numbered list, start each element of the list on a new line with a number and a period in front of it, like so:

1. The first item
2. The second item
3. The third item
5. The fourth item

Note that in the above example, the 5. will actually be shown as a 4. in the output. The list will follow sequentially whether you do or not, so you could type ones all the way down the line. This can be especially convenient when editing a list, because there is no necessity to change the numbers if an item needs to be inserted somewhere in the middle.

For an bulleted list, simply begin each line with a dash, an asterisk, or a plus sign rather than the number period in the ordered list.

Lists can also be mixed in an intuitive manner by indenting some and starting a different ordering scheme. An example may be the best illustration:

1. The first item
 - A sub-item
 - Another sub-item
2. The second item
 1. An ordered sub-item
 1. Another ordered sub-item
  - An unordered sub-sub-item

The above code will result in the following output:

  1. The first item
    • A sub-item
    • Another sub-item
  2. The second item
    1. An ordered sub-item
    2. Another ordered sub-item
      • An unordered sub-sub-item

Inline Code Snippets

You may have noticed that some key elements above have a different styling, like this. This is accomplished by surrounding the desired text by back-ticks, similar to putting a section of text in quotes. This should not be used in exactly the same place as quotes would, however, as it is properly used to portray short snippets of code, such as keyboard shortcuts, buttons to click on, function names, or other key words that fit more into this category than a quotation of something someone said or wrote. In case you are not sure what back-ticks are, here is an example:

Use the `calculate()` function

Emphasis

Markdown allows emphasizing text by placing it between asterisks or underscores, and strongly emphasizing text by placing it within pairs of the same. There is also the ability to strike text, as seen below:

First let's use some *emphasized* text, then proceed to some 
**strongly emphasized** text. We could also use _underscores_ 
in the __same__ manner as we used asterisks. For text that is 
no longer relevant, we can use ~~tildes~~.

which displays as:

First let's use some emphasized text, then proceed to some strongly emphasized text. We could also use underscores in the same manner as we used asterisks. For text that is no longer relevant, we can use tildes.

Fenced Code Blocks

There are many cases in which it is more appropriate to show a separate block that contains code or an algorithm. For this markdown provides fenced code blocks, which are sections of pre-formated text that is often syntax-highlighted according to a corresponding grammar. These sections are formed by "fencing" the desired text with a line of four back-ticks above the text and a line of four back-ticks below the text. In addition, the grammar to be used for syntax highlighting can be specified by typing the name of the language after the top "fence" of back-ticks. For example:

` ` ` `python
for i in range(10):
	x++
` ` ` `

renders as:

for i in range(10):
	x++

Note that indenting by four or more spaces will also trigger a code block, but if writing code for this website please use the syntax described above and indent with tabs rather than spaces.

Tables

Tables in Markdown are quite simple. Columns are separated by pipes, and column headings are separated from their cells by a row of dashes. It is recommended but not required to use spaces to line up the column divisions, as seen below:

Column One   | Column Two
-------------|--------------
First cell   | Second cell
Third cell   | Fourth cell

which produces:

Column One Column Two
First cell Second cell
Third cell Fourth cell

To alter the alignment of columns, colons can be added to the row of dashes that separates the column headers from the table body. For example:

A left aligned column | A right aligned column | A center aligned column
:---------------------|-----------------------:|:------------------------:
Cell                  | Cell                   | Cell

produces:

A left aligned column A right aligned column A center aligned column
Cell Cell Cell

Block Quotes

In Markdown, a block quote starts with a right angle bracket and a space before the desired text. It is common but not required to start each line of the quote with this character sequence. Here is an example:

> Here is a quote by so and so

displays as:

Here is a quote by so and so

LaTeX Equations

Although not all Markdown parsers provide this feature, the parser used on this website allows the ability to embed LaTeX equations into the Markdown syntax. For example:

$$ \int x^2 dx = \frac{x^3}{3} $$;

renders as:

$$ \int x^2 dx = \frac{x^3}{3} $$

Find more information about LaTeX in our [LaTeX] tutorial.

[latex]: /resources/tutorials/latex/

More Examples

One of the best ways to learn about a language is to look at examples. There are plenty more examples to view on this website. This page is written in Markdown, as well as the majority of the pages on this website. Pages that are written in Markdown have a View Page Source Code option that will display the Markdown code for that page. They even have an Edit Code option that brings up a Sublime Text style editor to edit the code in style with multiple cursors and other keyboard shortcuts.

< Up View Page Source Code Printer Friendly Version >