Markdown

Markdown is a mark-up language created by John Gruber in 2004. The spec has been available from his website, Daring Fireball, ever since:

He describes Markdown like this:

Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).

Thus, Markdown is two things: (1) a plain text formatting syntax; and …

The overriding design goal for Markdown's formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it's been marked up with tags or formatting instructions. While Markdown's syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown’s syntax is the format of plain text email.

Markdown is Everywhere

Markdown proved to be very popular. Support for it has popped up in all sorts of places. There are dedicated markdown editors and GitHub uses it extensively. Finally, there are many blogging systems that will accept markdown-formatted articles and convert them to HTML automatically.

Indeed, all of the Daring Fireball website is written in Markdown.

For instance, go to this URL: <http://daringfireball.net/linked/2015/08/28/panzerino-twotter>

Then, change it to this URL: <http://daringfireball.net/linked/2015/08/28/panzerino-twotter.text>

Markdown is thus a project that scratched an itch for John Gruber. It is an example of eating your own dog food: using your own software everyday.

HTML Allowed

Markdown's reason for existence is to take text and convert it to HTML. As a result, if there is something that HTML allows but Markdown doesn't support, just insert the HTML directly into the Markdown source. This applies to block level elements as well as in-line elements of HTML. See <http://daringfireball.net/projects/markdown/syntax> for details. For instance, the official version of Markdown does not support tables. So, in the official version of Markdown, if you need a table just add it using HTML's table, thead, tbody, tr, and td tags as needed to create the table. (Note: GitHub's version (or flavor) of Markdown does support tables.)

Example

          This is a [Markdown](http://daringfireball.net/projects/markdown/) paragraph

          <table>
            <tbody>
              <tr>
                <td>Row 1, Column 1</td>
                <td>Row 1, Column 2</td>
              </tr>
            </tbody>
          </table>

          This is a second Markdown paragraph

Result

This is a Markdown paragraph

Row 1, Column 1 Row 1, Column 2

This is a second Markdown paragraph

Why?

Why did I present this information?

Because GitHub uses Markdown everywhere and even adds new features to Markdown. What does GitHub add to Markdown?

  • URL auto-linking
  • Free ponies! Strikethrough text
  • Fenced code blocks and syntax highlighting
  • Tables

Trying out the Examples

Note: You can try out any of the examples shown in this lecture.

Head to: <http://daringfireball.net/projects/markdown/dingus> and then cut-and-paste the example text into the dingus and click on the convert button.

You can also use GitHub as a Markdown editor. Just:

  • Create a new repo and indicate that it should have a README.md file created automatically.
  • Edit the README.md file and put any Markdown text that you want.
  • Flip to the Preview tab at any point to see the Markdown rendered as HTML.

Next Steps

Head to the Markdown Basics to learn about the syntax of Markdown or head back to the Table of Contents.