Markup with Markdown

Technical writers have relied on a variety of technologies and tools over the years. Each comes with pros and cons, benefits and gotchas. But most of all, each new writing technology requires learning a new set of markup codes; for example, LATEX, groff, and HTML are all quite different.

Markdown aims to provide a middle ground; Markdown documents use unobtrusive formatting codes. Most of Markdown borrows existing conventions from writing in plain text: underline text with = or - to create first level and second level headings, surround text with * or ** for italics and bold style, and add a blank line to start a new paragraph.

If you're getting started in Markdown, let's explore some advanced formatting you can create in Markdown documents.

Document headings

Markdown borrowed the convention of underlining text to create a section heading:

Top level heading
=================

Second level heading
--------------------

This looks very natural in plain text files, and Markdown converts text underlined by = to <h1> and text underlined with - to <h2> section headings.

<h1>Top level heading</h1>

<h2>Second level heading</h2>

Another way to provide document headings is with the # character. Surround a heading with # on either side to create a first level heading, or ## for a second level heading. Minimally, you just need it on the left side, but I find it looks better as plain text file to include the # or ## on both left and right sides:

# Top level heading #

## Second level heading ##

Markdown converts # text to <h1> and ## to <h2> section headings.

<h1>Top level heading</h1>

<h2>Second level heading</h2>

Block quotes

Some technical documents benefit from including long quotes. These block quotes might provide background information, situational context, or just inspirational quotes.

Markdown borrows from a longstanding email convention. When replying to email as plain text, email clients typically quote the previous email by inserting > before each line of the first message. Markdown does the same:

> This is a block quote.
>
> This is the second paragraph of a block quote.

Markdown converts this text to <blockquote> as HTML.

<blockquote>
  <p>This is a block quote.</p>

<p>This is the second paragraph of a block quote.</p>
</blockquote>

Ordered and unordered lists

Markdown also borrows from plain text conventions in creating lists. To make a numbered or ordered list in Markdown, simply type the list with numbers before each item.

1. This is the first step
2. The second step
3. The last step

Markdown will recognize the numbers and turn the text into an ordered list using <ol>.

<ol>
<li>This is the first step</li>
<li>The second step</li>
<li>The last step</li>
</ol>

To type a list in a plain text file, authors typically use some recognizable character to represent a bullet mark. Some writers prefer an asterisk, others use a plus sign, others use a hyphen. Markdown treats each as a valid unordered list item:

* The first item
+ The second item
- The third item

When processed through Markdown, the list becomes a <ul> unordered list.

<ul>
<li>The first item</li>
<li>The second item</li>
<li>The third item</li>
</ul>

Hyperlinks

Links to other web pages via Markdown require a special character sequence. This is one of the few areas in Markdown that doesn't look like a plain text file. The general format of a link is [link text](link target), like this:

For more information about Markdown, visit the
[Markdown home page](https://daringfireball.net/projects/markdown/)

Markdown recognizes the brackets and parentheses and converts the text into an HTML <a> link.

<p>For more information about Markdown, visit the
<a href="https://daringfireball.net/projects/markdown/">Markdown home page</a></p>

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.