Introduction to Markdown

The easiest format to write documentation is plain text. But plain text lacks the ability to style certain text to indicate "this is program input" and other text to indicate "this is a list."

A more universal format to write documentation is HTML. But writing in HTML can be difficult for folks whose primary job responsibility doesn't involve writing in HTML.

A middle ground is a text formatting system that lies somewhere between plain text and HTML. That's where Markdown tries to fit in.

Getting started in Markdown

Markdown documents are just plain text files that use a formatting syntax that most people already use anyway. The Markdown home page says as much: "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." For example, paragraphs are just lines of text; start a new paragraph by adding a blank line.

Here's an example:

This is a Markdown file.  A Markdown file just looks like
a regular text file.

To turn Markdown into HTML so you can display it in a web
browser, you need to run a command.

Save the sample text to a new file called readme, then run the Markdown.pl script to convert it to HTML:

$ Markdown.pl readme
<p>This is a Markdown file.  A Markdown file just looks like
a regular text file.</p>

<p>To turn Markdown into HTML so you can display it in a web
browser, you need to run a command.</p>

Headings and subheadings

Simple documents might be just paragraphs of text, but more complex documents may require headings and subheadings. Markdown borrows a syntax that has been used in plain text documents since at least the 1980s: underlined text using ASCII characters.

Let's add a heading or title to our Markdown file; we'll call it "Readme." To mark text as a top-level heading, underline it using the equals sign. Before each paragraph, we'll add separate subheadings. To indicate text is a subheading, underline it using a series of dashes.

The updated readme file should look like this:

Readme
======

Sample Markdown file
--------------------

This is a Markdown file.  A Markdown file just looks like
a regular text file.

How to use it
-------------

To turn Markdown into HTML so you can display it in a web
browser, you need to run a command.

Processing the new file through Markdown gives top-level headings as <h1> and subheadings as <h2>:

$ Markdown.pl readme
<h1>Readme</h1>

<h2>Sample Markdown file</h2>

<p>This is a Markdown file.  A Markdown file just looks like
a regular text file.</p>

<h2>How to use it</h2>

<p>To turn Markdown into HTML so you can display it in a web
browser, you need to run a command.</p>

Basic formatting

Adding other formatting such as bold and italics also borrows from plain text file conventions. For example, to put text in italics, add asterisks on either side. To make bold text, use double asterisks:

Readme
======

Sample Markdown file
--------------------

This is a Markdown file.  A Markdown file just looks like
a regular text file. This text is *italics* and this is
**bold**.

How to use it
-------------

To turn Markdown into HTML so you can display it in a web
browser, you need to run a command.

Note that when you process the new file, Markdown correctly recognizes that the word "bold" should be bold, but not the period that follows it:

$ Markdown.pl readme 
<h1>Readme</h1>

<h2>Sample Markdown file</h2>

<p>This is a Markdown file.  A Markdown file just looks like
a regular text file. This text is <em>italics</em> and this is
<strong>bold</strong>.</p>

<h2>How to use it</h2>

<p>To turn Markdown into HTML so you can display it in a web
browser, you need to run a command.</p>

Technical documents may need to include source code or provide inline code formatting such as commands. Inline code uses the "backtick" character, similar to how Unix environments use the backtick to run commands in a separate shell but include the output in a command line. Add a tab or 4 spaces before each line in a code block.

Let's update the readme file to include both block and inline code samples:

Readme
======

Sample Markdown file
--------------------

This is a Markdown file.  A Markdown file just looks like
a regular text file. This text is *italics* and this is
**bold**.

How to use it
-------------

To turn Markdown into HTML so you can display it in a web
browser, you need to run the `Markdown.pl` command:

    $ Markdown.pl readme > index.html

Note that the generated output converts HTML special characters like ampersand, less than, and greater than into HTML entities:

$ Markdown.pl readme
<h1>Readme</h1>

<h2>Sample Markdown file</h2>

<p>This is a Markdown file.  A Markdown file just looks like
a regular text file. This text is <em>italics</em> and this is
<strong>bold</strong>.</p>

<h2>How to use it</h2>

<p>To turn Markdown into HTML so you can display it in a web
browser, you need to run the <code>Markdown.pl</code> command:</p>

<pre><code>$ Markdown.pl readme &gt; index.html
</code></pre>

Try it out

Markdown makes it easy to convert text into HTML. Using conventions you may already be familiar with for writing plain text documentation, you can write Markdown documentation that otherwise looks like plain text.

For more information on basic formatting with Markdown, read Markdown: Basics on the Markdown home page.