A Guide to Markdown

Markdown is a simple way to add formatting to plain text, like making text bold, creating lists, or adding links. It’s easy to learn, quick to use, and works great for writing notes, blog posts, or documents.

Markdown is also popular because of its versatility. Any application that can open plain text files can open Markdown, so you’re never locked into using a single app like Paragraphs to view or edit your files.

Whether you’re new to it or just want a refresher, this guide will walk you through the basics of Markdown and show you how to use it to make your writing look great with minimal effort.

Formatting Text

Markdown makes it easy to format text directly in your document. You can emphasize words, make them stand out, or even show small snippets of code. Here’s how to use some of the most common inline formatting options:

Bold Text

To make text bold, wrap it in double asterisks ** or double underscores __:

**This text is bold**
__This text is also bold__

Italic Text

For italicized text, use single asterisks * or single underscores _:

*This text is italicized*
_This text is also italicized_

Strikethrough

To create a strikethrough, wrap the text in double tildes ~~:

~~This text has a strikethrough~~

Inline Code

For inline code snippets, surround the text with backticks `:

This is `inline code`

To add a hyperlink, use square brackets for the text you want to display, followed by the link in parentheses. You can also press Shift+⌘+K to insert an empty link.

[Visit the Paragraphs Homepage](https://www.paragraphs.app)

Results in the following:
Visit the Paragraphs Homepage

 

Tip:
You can also (optionally) include a title that appears when you hover over the link:

Example:

[Visit the Paragraphs Homepage](https://www.paragraphs.app "...and download the app")

Results in the following (Hover over the link to see the title): Visit the Paragraphs Homepage

Headings

Headings in Markdown let you structure your text into clear sections, making it easier to read and organize. They work by using one or more hash symbols # followed by a space, with the number of hash symbols indicating the heading level. Markdown supports six levels of headings:

# Title or first-level heading
## Subtitle or second-level heading
### A third-level heading
#### A forth-level heading
##### A fifth-level heading
###### A sixth level heading

Blockquotes

Blockquotes are a way to highlight important text, cite references, or display a block of quoted material. You create quotes using the > symbol followed by the quoted text.

Use one > for each new line.

> Writing is like driving at night in the fog. 
> You can only see as far as your headlights, 
> but you can make the whole trip that way.
>
> _E.L. Doctorow_

Results in the following:

Writing is like driving at night in the fog. You can only see as far as your headlights, but you can make the whole trip that way.

E.L. Doctorow

Alerts

Paragraphs supports a special variety of Blockquotes called Alerts:

> [!NOTE]
> Highlights information that users should take into account, even when skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Crucial information necessary for users to succeed.

> [!CAUTION]
> Negative potential consequences of an action.

> [!WARNING]
> Critical content demanding immediate user attention due to potential risks.

Results in:

Note:
Highlights information that users should take into account, even when skimming.

Tip:
Optional information to help a user be more successful.

Important:
Crucial information necessary for users to succeed.

Caution:
Negative potential consequences of an action.

Warning:
Critical content demanding immediate user attention due to potential risks.

Code Blocks

Code blocks in Markdown are a great way to display multiple lines of code or technical content in a clean, readable format. While inline code uses single backticks `, code blocks are created using triple backticks ```. This is especially useful when sharing programming examples or configuration snippets.

10 PRINT "HELLO WORLD"
GOTO 10

Results in the following:

10 PRINT "HELLO WORLD"
GOTO 10

Syntax Highlighting

You can specify a language after the opening triple backticks (```) to enable syntax highlighting:

def hello_world():
    print("Hello, World!")

Lists

Paragraphs supports three types of list formats: unordered lists, ordered lists, and task lists (specific to GitHub Flavored Markdown, or GFM). Each has its own simple syntax:

Dashed Lists

Dashed lists are created using dashes (-), plus signs (+), or asterisks (*) followed by a space:

* Pencil
* Eraser
* Notebook

Results in:

Numbered Lists

Numbered lists use numbers followed by a period (1.), with items listed in order:

1. Begin writing
2. Create the next great American novel
3. ???
4. Profit

Results in:

  1. Begin writing
  2. Create the next great American novel
  3. ???
  4. Profit

Task Lists

Paragraphs supports the Task Lists Markdown extension.

Use a dash - followed by [ ] for unchecked items and [x] for checked ones:

- [x] Pencil
- [ ] Eraser
- [ ] Notebook

Results in:

Tables

Tables in Markdown allow you to organize data into rows and columns using dashes - and pipes |

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Row 1    | Data     | More Data|
| Row 2    | Info     | Details  |

Results in:

Header 1 Header 2 Header 3
Row 1 Data More Data
Row 2 Info Details
Keyboard Shortcuts