Getting Started With Markdown in 15 Minutes

Project Brief

Audience: Non-technical users (spec work).
User Goal: To get started using basic Markdown.
Problem: Markdown is simple enough to be useful for non-technical users, but the jargon surrounding it can be intimidating.
Scope: This guide covers a selection of core Markdown syntax.
Key Considerations:
- A visual approach to showing how syntax is rendered aids user comprehension by avoiding jargon and showing results directly.
- Reference-style links are excluded as being too complex for the user goal.
- An example document with multiple different Markdown formatting elements shows Markdown used in practice.
Success Criteria: The user can demonstrate marking up text with each specified Markdown element.
Validation: Test with first-time users against the success criteria.

Sample

Markdown is a simple way to format text for display on the web and related applications. You simply write the text you want and then use symbols such as * and _ to tell the computer how you want to display the text. Markdown is widely used across various platforms for tasks such as formatting blog posts, writing messages, and taking notes. This quick-start guide is meant for non-technical users and will show you how to get started with core Markdown formatting in 15 minutes. If you decide to do the exercises, budget up to 30 minutes.

Note: Markdown comes in different versions, which are called flavors. For example, GitHub uses GitHub Flavored Markdown. In some cases, you may need or want to take into account the flavor being used. This guide covers core Markdown formatting without examining different flavors.

Headings

You can format headings using hashes #. For example:

# Heading

will show as

Heading

There are six heading levels. Use one hash for the largest size and six hashes for the smallest size. For example, # Heading and ###### Heading.

Optional Practice: Make a series of headings from one hash to six.

Bold and Italic Text

To make text bold, use two asterisks ** before and after the text. For example:

**Bold**

will show as

Bold

To make text italic, use an underscore _ or a single asterisk * before and after the text. For example:

_Italic_

will show as

Italic

and

*Italic*

will show as

Italic

Optional Practice: Write a sentence with one bold word, one italic word using underscores, and one italic word using single asterisks.

Inline Links

Inline links place the link directly in the line of text (hence the name). To insert an inline link, place the desired link text in brackets and place the link URL in parentheses immediately following the brackets. For example:

[CommonMark](https://spec.commonmark.org/) is a formal specification for Markdown.

will show as

CommonMark is a formal specification for Markdown.

Best practice is to use descriptive text such as CommonMark rather than generic text such as Click here when formatting link text.

Optional Practice: Make an inline link with descriptive link text and a URL to a Wikipedia page.

Images

To insert an image, add an exclamation mark followed by alt text in brackets and then the image URL in parentheses. For example:

![View from the South Rim of the Grand Canyon](https://upload.wikimedia.org/wikipedia/commons/f/f0/Grand_Canyon_National_Park_-_HCP_-_September_29%2C_2022_-_058_-_Southern_Rim.jpg)

will show as

View from the South Rim of the Grand Canyon

Alt text describes the image for screen readers and other assistive devices. While you cannot see the alt text visually, it is still present.

Optional Practice: Insert an image using the URL above and relevant alt text.

Ordered and Unordered Lists

There are two types of lists: ordered and unordered. Ordered lists have a sequential order (such as 1, 2, 3, …), while unordered lists do not. Markdown displays ordered lists using numbers. To make an ordered list, use a number followed by a period before each list item. For example:

1. List Item 1  
2. List Item 2  

will show as

List Item 1
List Item 2

Markdown uses bullet points to display unordered lists. To make an unordered list, use an asterisk or hyphen before each list item. For example:

* List Item 1
* List Item 2

will show as

List Item 1
List Item 2

and

- List Item 1
- List Item 2

will show as

List Item 1
List Item 2

Optional Practice: Make three lists: an ordered list with three items, an unordered list with three items using asterisks, and an unordered list with three items using hyphens.

Code

To display text as inline code, use a single backtick ` before and after the text. For example:

`Code`

will show as

Code

To display text in a code block, place triple backticks on the line above the text and the line below the text. For example:

``` 
Code 
```

will show as

Code

Note that the text is now displayed in the darker-colored code block inside the lighter-colored display box.

Optional Practice: Write a code sample, real or invented, and enclose it first in single backticks for inline code and then in triple backticks for a code block.

Blockquotes

To format text as a blockquote, use a right angle bracket > before the text. For example:

Preceding Text  
> Blockquote

will show as

Preceding Text

Blockquote

Note: The appearance of a blockquote can vary depending on the website or application.

Optional Practice: Choose a favorite quote, write some comments about it, and then insert the quote as a blockquote inside the comments.

Applications

Here are some ways Markdown can be used:

Reddit: You can add Markdown formatting directly to text in the post composer when using the Markdown Editor.
Ghost: You can use Markdown to format blog posts.
Discord: You can use Markdown to format messages.
Obsidian: You can store notes as Markdown files.
Any Plain-Text Editor: You can write Markdown in any plain-text editor and then convert it to other formats, such as PDF, with the right tools.

Mistakes to Avoid

Not having a space between the symbol and the text for headings and lists. For example, #Heading would be incorrect, while # Heading would be correct.
Forgetting to close formatting marks. For example, [link text](URL would be incorrect, while [link text](URL) would be correct.
Reversing brackets and parentheses for links. For example, (Link Text)[URL] would be incorrect, while [Link Text](URL) would be correct. Remember by: Brackets for Buttons and Parentheses for Path.

Tips

Applications vary with respect to supporting Markdown. Use the preview feature, if available, to ensure your Markdown renders correctly.
If Markdown is rendering a character that you don’t want to render, use a backslash \ to escape it. For example, \_Italic\_ will show as _Italic_ (underscores visible).
If an image doesn’t display, make sure the path and file name are correct, including spaces and capitalization.
Try adding a blank line before and after elements such as headings if the elements don’t render correctly.

Example

Here is an example of text formatted with Markdown and the rendered result:

# Weekly Project Meeting Notes

## Agenda

1. Status updates
2. Decisions required
3. Risks / blockers
4. Next steps

## Status

* **Installation Guide:** 90% complete
* **Troubleshooting Guide:** Draft ready for review
* **Open Question:** Who should draft the quick start? 

## Decisions

* Sarah will draft the quick start beginning next week. 

## Risks / Blockers

* Two members of the dev team are on vacation, so some details on the quick start may need to wait.

## Next Steps

* Sarah will check with the dev team and report to the product manager. 

The rendered result:

Weekly Project Meeting Notes

Agenda

Status updates
Decisions required
Risks / blockers
Next steps

Status

Installation Guide: 90% complete
Troubleshooting Guide: Draft ready for review
Open Question: Who should draft the quick start?

Decisions

Sarah will draft the quick start beginning next week.

Risks / Blockers

Two members of the dev team are on vacation, so some details on the quick start may need to wait.

Next Steps

Sarah will check with the dev team and report to the product manager.

Optional Practice: Copy-paste the Markdown text above into your editor of choice to see the rendered result. A free editor you can use online is Dillinger.

Recommended Resources

Practice Now

Dillinger allows you to quickly write Markdown online and see the results immediately.
Selecting the Markdown Editor in the Reddit post composer is an easy way to practice. You first need to navigate to a community and then create a post/respond to a post. Once you are creating or responding to a post, make sure you select the Markdown Editor.

Learn More

A Markdown tutorial is available.
A guide to Markdown by Matt Cone is available both in PDF format and online. Physical copies are also available on Amazon.

Final Step

Learning Markdown takes practice. Use one of the resources above to get started.