Skip to content

Markdown Cheatsheet#

Markdown is a lightweight markup language that you can use to format text. Here's everything you need to know.

Quickstart#

# H1

## H2

### H3

*bold*

_italicize_

<u>underline</u>

[link text](link)

--- or *** for horizontal gray divider line

> quote

`codeblock`

- item 1 for bulleted list

1. item 1 for numbered list

!!! example
    This is an information box.

View all box types available here

Table:

| Column 1 | Column 2 |
|----------|----------|
|          |          |
|          |          |

![image title](image source)

Headings#

Use # for headings. The number of # symbols determines the level of the heading.

# Heading 1

Heading 1#

## Heading 2

Heading 2#

### Heading 3

Heading 3#

Font formatting (bold, italicize, underline)#

*This text is bold.*

This text is bold.

__This text is also bold.__

This text is also bold.

Markdown itself does not support underlining, but it will allow HTML tags:

<u>This text is underlined.</u>

This text is underlined.

You can combine these formats in different ways.

**Bold and _italic_ text.**

Bold and italic text.

and you can use different formatting in one sentence.

This **word** is bold and this _word_ is italicized and this <u>word</u> is underlined

This word is bold and this word is italicized and this word is underlined

Bullet points & numbered lists#

- item 1

- item 1

- item 3

  • item 1
  • item 2
  • item 3

1. item 1

2. item 2

3. item 3

  1. item 1
  2. item 2
  3. item 3

Sometimes, when writing long chunks of text, your bullet points might not be showing up if the text is mushed too close together. For example:

This is a long line written at the start of my bulleted list: - item 1 - item 2 - item 3

This is that same long line written at the start of my bulleted list with a Return between this line and the first listed item:

  • item 1
  • item 2
  • item 3

Breakpoints / Line breaks / Page breaks / Horizontal grey line#

It's useful to use the horizontal grey line that Markdown offers as a way to break up content on a page and make it easier for readers.

This is easily done with --- or ***. You can see it in use below this line and between each section on this page.

Codeblock#

Add a codeblock with a single backtick apostrophe, like `.

`This is a codeblock`

This is a codeblock

Block quote#

Add a block quote with > at the start of the line.

> This is a block quote

This is a block quote

Information boxes (Admonitions)#

We are using the Material theme in Markdown, so our information boxes are called "admonitions". There are several great ones available, and they're all formatted the same way.

!!! example
    This is an example box

All boxes start with three exclamation marks !!! followed by a space and the type of admonition (quote, note, tip, etc.) Then hit Return and add four spaces before the next line. Depending on how many spaces your Tab key adds, you can also use the Tab key. For example, my Tab key adds two spaces each time I hit it, so I hit Tab twice.

Quote

This is a quote box

Example

This is an example box

Note

This is a note box

Tip

This is a tip box

Info

This is an information box

Warning

This is a warning box

Caution

This is a caution box

Danger

This is a danger box

Success

This is a success box

Bug

This is a bug box

You can add custom titles to your admonitions#

!!! info "Custom Title"
    This is an info box with a custom title

Custom Title

This is an informational box with a custom title

Nesting one admonition inside another#

!!! note
    This is the outer note.

    !!! warning
        This is a warning nested inside the note.

Note

This is the outer note.

Warning

This is a warning nested inside the note.

Tables#

Tables in Markdown are a combination of | vertical lines and --- horizontal dashes. For example, this is a simple table with two columns and three rows. The first row is the header row.

| Column 1 | Column 2 |
|----------|----------|
|          |          |
|          |          |

This renders like this on the page.

Column 1 Column 2

To hyperlink text, wrap the text you want hyperlinked in [square brackets] and place the link next to it in (round brackets), like so.

[This text is hyperlinked](https://www.amazee.io/)

This text is hyperlinked

Images#

If you are linking to an image that exists at a static URL somewhere, then you can use this syntax to link to the image source directly.

![image title](image source)

For example: ![duck](https://www.shutterstock.com/image-photo/call-duck-historic-breed-small-600nw-2296660877.jpg)

renders as

duck

However, if you wish to add an image of your own to a page, that can be a bit more complicated, so please reach out to Kelly Knight on Slack in the #team-public-handbook channel for support.

  1. Open the Handbook GitLab project in your IDE of choice. I use Visual Studio Code.

  2. Navigate to the assets folder where the images are saved. You can find this in the left-hand docs nav.

    assets-example

  3. Open the folder on your computer where your image is saved, and click and drag it into the assets folder.

    assets-example-click-and-drag

  4. You should now be able to see your new assets in the assets folder.

    assets-example-new-assets

  5. This is the syntax for adding an image:

![optional image title](link to image in your project)

If the image title is left blank, be sure to keep the square brackets, you can just leave them empty, like [].

There is a lot more Markdown can do but a lot of the more advanced formatting options aren't used day-to-day and are rarely used in this handbook, so these have not been included here. Please Google "Markdown cheatsheet" for more information on Markdown formatting options or reach out to Kelly Knight on Slack in the #team-public-handbook channel if there's something you'd like to try that hasn't been listed here.