Your quick-start guide to Markdown

Markdown is a simplified document markup system that makes it easy to write documentation quickly. Most people find Markdown is easy to learn because it is based on de facto standards that developers adopted long ago when writing their own documentation in plain text—so the formatting should be fairly straightforward in most use cases. For example, to start a new paragraph, just add a blank line. Line breaks within a paragraph have no special meaning.

Here’s a brief overview of the most common formatting that you can do with Markdown. Note that Markdown is not a well defined standard, but most Markdown implementations should support the basic syntax. I’ll stick to what should be supported everywhere.

Headings

Documents usually start with a title or top-level heading. Even as far back as the 1980s and 1990s, developers would often write a title with a row of “equal” signs under the text, to suggest a “double underline.” Similarly, developers might write a subheading with a row of dashes to suggest a “single underline.” Markdown formats these as headings and subheadings:

Read me first
=============

About the program...

How to install
--------------

How to install it...

Over time, other developers adopted a style of using different “hash” marks to indicate up to six heading levels:

# Heading 1 (top-level heading)

## Heading 2 (subheading)

### Heading 3

#### Heading 4

##### Heading 5

###### Heading 6

Markdown accepts both the “underline” style or “hashes” style, and will format either as headings and subheadings. I usually write my Markdown documents using hashes for headings, because I find that easier to read.

Italics and bold

To format text in italics, put a _single underline_ around the word or phrase. To format text as bold, use **two asterisks** around the word or phrase. Markdown also accepts a *single asterisk* for italics and __two underlines__ for bold text.

Format text as **bold** or **italics.**
Or format text as __bold__ or _italics._

Lists

To write a list in Markdown, it helps to think about how you might represent a “list” in a plain text editor. To write an unordered list, start each list item with a dash, like this:

Several common types of DITA files:

- Concepts
- Tasks
- References

You can also start each list item with an asterisk:

Several common types of DITA files:

* Concepts
* Tasks
* References 

For example, an unordered list will be formatted as a “bullet” list, like this:

• Concepts
• Tasks
• References

To create an ordered list (numbered list), start each list item with a number:

How to build a DITA Map:

1. Use the **Append child - Reference** menu
2. Select one or more files to add
3. Click **Insert and close**

Quotes

There is no “inline quote” style in Markdown. Instead, to write an inline quote, just use double quotes like you would if you were writing it in an email. Some Markdown implementations will interpret the quotes and translate them to curly quotes, but not all systems do.

For block quotes, Markdown borrows from an old email standard. To format a block quote, add a “greater than” symbol (>) before each line, like this:

> Some Markdown implementations will interpret the
> quotes and translate them to curly quotes, but not
> all systems do.

Links and images

To create a link, enclose the link text in square brackets, followed by the URL in parentheses, like this:

[Technically We Write](https://technicallywewrite.com/)

I like to think of links as a pairing of text (in brackets) and destination (in parentheses). This helps me to remember how to format an image in Markdown, which uses a similar syntax: the image text (in brackets) and image source (in parentheses), but with an exclamation point (!) up front:

![Jim Hall author photo](photo.jpg)

You can also provide a full URL to the image, like this:

![Jim Hall author photo](https://technicallywewrite.com/authors/jhall/photo.jpg)

This inserts the image into the document. But it’s important to remember that Markdown doesn’t resize the image for you, so the image should already be sized appropriately for the content. Also, images are inline by default, although some Markdown implementations will interpret an image reference on a line by itself as a figure and format it accordingly:

Markdown will use the image text (in brackets) to define alternative text so that screen readers will provide a description of the image. This is one way to ensure your documents are accessible to all users.

Tables

Tables are an extended syntax in Markdown, and may not be implemented the same way in every system. To define a table, think about how you might “draw” a table using plain text: use a vertical line (|) to separate columns and three or more dashes to separate the header row from the rest of the table:

| Binary | Value |
| ------ | ----- |
| 0001   | 1     |
| 0010   | 2     |
| 0011   | 3     |

You can align the text in each column by adding a colon (:) to the left (to left-align), right (to right-align), or both sides (center).

| Name  | Binary | Value |
| :---- | -----: | :---: |
| One   | 0001   | 1     |
| Two   | 0010   | 2     |
| Three | 0011   | 3     |

Some Markdown implementations may also insert a figure element around the table:

Getting started with Markdown

I love writing documents in Markdown. For most of the articles that I write, I’ll often write the first version in Markdown, then convert it to another format like HTML or LibreOffice using a tool like Pandoc. With Markdown, I can focus on the content of what I’m writing without worrying about the markup to make it look nice.