Markdown guide

Markdown is a lightweight markup language that allows you to add formatting to plain text documents.

Paragraphs and line breaks

To create paragraphs, use a blank line to separate one or more lines of text.

Markdown	Rendered output
This is the first paragraph. And this is the second one.	This is the first paragraph. And this is the second one.

This is the first paragraph.

And this is the second one.

This is the first paragraph.

And this is the second one.

To create a line break or new line (<br>), end a line with 2 or more spaces, and then type return.

Markdown	Rendered output
This is the first line. And this is the second one.	This is the first line. And this is the second one.

Headings

To create a heading, add number signs (#) in front of a word or phrase.

The number of number signs you use should correspond to the heading level. For example, to create a heading level 3 (<h3>), use 3 number signs (e.g., ### My Header).

Markdown	Rendered output
`# Heading level 1`	Heading level 1
`## Heading level 2`	Heading level 2
`### Heading level 3`	Heading level 3
`#### Heading level 4`	Heading level 4
`##### Heading level 5`	Heading level 5
`###### Heading level 6`	Heading level 6

Horizontal rules

To create a horizontal rule, use 3 or more asterisks (***), dashes (---), or underscores (___) on a line by themselves.

***
---
___

The rendered output of all 3 looks identical:

Blockquotes

To create a blockquote, add a > in front of a paragraph.

> Many forms of Government have been tried, and will be tried in this world of sin and woe. No one pretends that democracy is perfect or all-wise.

The rendered output looks like this:

Many forms of Government have been tried, and will be tried in this world of sin and woe. No one pretends that democracy is perfect or all-wise.

Blockquotes with multiple paragraphs

Blockquotes can contain multiple paragraphs. Add a > on the blank lines between the paragraphs.

> Many forms of Government have been tried, and will be tried in this world of sin and woe. No one pretends that democracy is perfect or all-wise.
>
> Indeed, it has been said that democracy is the worst form of government except all those other forms that have been tried from time to time.

The rendered output looks like this:

Many forms of Government have been tried, and will be tried in this world of sin and woe. No one pretends that democracy is perfect or all-wise.

Indeed, it has been said that democracy is the worst form of government except all those other forms that have been tried from time to time.

Blockquotes with attribution

You can attribute a quote to its author by adding two hyphens (--) before the attribution you want to add.

> Many forms of Government have been tried, and will be tried in this world of sin and woe. No one pretends that democracy is perfect or all-wise.
>
> Indeed, it has been said that democracy is the worst form of government except all those other forms that have been tried from time to time.
>
> -- Winston Churchill, [in a speech to the House of Commons](https://hansard.parliament.uk/Commons/1947-11-11/debates/ab1e1152-6b4a-4d04-ac38-954df6634b08/ParliamentBill#207). 11th November 1947

The rendered output looks like this:

Many forms of Government have been tried, and will be tried in this world of sin and woe. No one pretends that democracy is perfect or all-wise.

Indeed, it has been said that democracy is the worst form of government except all those other forms that have been tried from time to time.

Winston Churchill, in a speech to the House of Commons. 11th November 1947

Alerts

Alerts, based on the blockquote syntax, can be used emphasise critical information. On GitHub they are displayed with distinctive colors and icons, while pages rendered by the plugin use the inset text component from the GOV.UK Design System.

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

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

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

The rendered output for the note alert type uses the standard design for inset text:

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

The rendered output for other alert types uses inset text with a coloured border and background:

Optional information to help a user be more successful.

Key information users need to know to achieve their goal.

Urgent info that needs immediate user attention to avoid problems.

Advises about risks or negative outcomes of certain actions.

You can also include a title:

> [!NOTE] Check the MOT status of a vehicle
>
> If your vehicle is new, you must [get an MOT test](https://www.gov.uk/getting-an-mot) by the third anniversary of its registration.

The rendered output looks like this:

Note: Check the MOT status of a vehicle

If your vehicle is new, you must get an MOT test by the third anniversary of its registration.

Lists

Ordered lists

To create an ordered list, add line items with numbers followed by periods. The numbers don’t have to be in numerical order, but the list should start with the number one.

1. First item
2. Second item
   1. Indented item
   1. Indented item
3. Third item

First item
Second item
1. Indented item
2. Indented item
Third item

Unordered lists

To create an unordered list, add dashes (-), asterisks (*), or plus signs (+) in front of line items. Indent one or more items to create a nested list.

- First item
- Second item
  - Indented item
  - Indented item
- Third item

First item
Second item
- Indented item
- Indented item
Third item

Nesting different list types

You can also nest an unordered list in an ordered list, or vice versa.

1. First item
2. Second item
   - Indented item
   - Indented item
3. Third item

First item
Second item
- Indented item
- Indented item
Third item

Starting unordered list items with numbers

If you need to start an unordered list item with a number followed by a period, you can use a backslash (\) to escape the period.

- 2012\. A great year!
- I think 2009 was second best.

2012. A great year!
I think 2009 was second best.

Description lists

To create a description list, type the term on the first line. On the next line, type a colon followed by a space and the description.

First Term
: This is the description of the first term.

Second Term
: This is one description of the second term.
: This is another description of the second term.

The rendered output looks like this:

First Term: This is the description of the first term.
Second Term: This is one description of the second term.; This is another description of the second term.

Contents list

To add a table of contents, add the following Markdown where you want the list to appear on the page:

[[toc]]

Code

Code spans

To denote a word or phrase as code, enclose it in backticks (`).

At the command prompt, type `npm install`.

At the command prompt, type npm install.

Code blocks

By default, Eleventy doesn’t support the Markdown syntax for indented code blocks because pages can render incorrectly should a layout or component include indented markup.

To include code blocks in your documentation, you should use fenced code blocks instead. These use 3 backticks (```) or 3 tildes (~~~) on the lines before and after the code block.

```
{
  "firstName": "William",
  "lastName": "Pitt",
  "age": 24
}
```

The rendered output looks like this:

{
  "firstName": "William",
  "lastName": "Pitt",
  "age": 24
}

Syntax highlighting

This feature allows you to add color highlighting different programming languages. To add syntax highlighting, specify a language next to the backticks before the fenced code block.

```json
{
  "firstName": "William",
  "lastName": "Pitt",
  "age": 24
}
```

The rendered output looks like this:

{
  "firstName": "William",
  "lastName": "Pitt",
  "age": 24
}

Emphasised text

To emphasise text, add one asterisk or underscore before and after a word or phrase.

The GDS Style Guide recommends against the use of italics, and the GDS Transport font doesn’t provide an italic style. Use ‘single quotation marks’ if referring to a document, scheme or initiative.

Markdown	Rendered output
`This text is emphasised.`	This text is emphasised.
`This text is _emphasised_.`	This text is emphasised.

Strongly emphasised text

To bold text, add 2 asterisks or underscores before and after a word or phrase.

The GDS Style Guide recommends using emboldened text when referring to text from interfaces in technical documentation or instructions.

Markdown	Rendered output
`This text is strongly emphasised.`	This text is strongly emphasised.
`This text is __strongly emphasised__.`	This text is strongly emphasised.

Deleted text

To show that certain words are a mistake not meant for inclusion in the document, use 2 tilde symbols (~~) before and after the words.

~~The world is flat.~~ We now know that the world is round.

The rendered output looks like this:

~~The world is flat.~~ We now know that the world is round.

Inserted text

To show inserted text, use 2 plus signs (++) before and after the words. You can use this alongside the syntax for deleted text.

I need to ~~remove~~ ++insert++ a word.

The rendered output looks like this:

I need to ~~remove~~ insert a word.

Highlighted text

To highlight words, use 2 equal signs (==) before and after the words.

I need to highlight these ==important words==.

The rendered output looks like this:

I need to highlight these important words.

Subscript and superscript text

For subscript text, use one tilde symbol (~) before and after the characters.

H~2~O

The rendered output looks like this:

H₂O

For superscript text, use one caret symbol (^) before and after the characters.

X^2^

The rendered output looks like this:

X²

Links

To create a link, enclose the link text in brackets (e.g., [GOV.UK]) and then follow it with the URL in parentheses (e.g., (https://www.gov.uk)).

Visit [GOV.UK](https://www.gov.uk).

The rendered output looks like this:

Visit GOV.UK.

URLs and email addresses

To turn a URL or email address into a link, enclose it in angle brackets.

<https://www.gov.uk>
<mailbox@example.org>

The rendered output looks like this:

https://www.gov.uk
mailbox@example.org

Formatting links

To emphasise links, add asterisks before and after the brackets and parentheses. To denote links as code, add backticks in the brackets.

Visit the **[Markdown Guide](https://www.markdownguide.org)**.
See the section on [`code`](#code).

The rendered output looks like this:

Visit the Markdown Guide.
See the section on code.

Images

To add an image, add an exclamation mark (!), followed by alternative text in brackets, and the path or URL to the image asset in parentheses. You can optionally add a caption in quotation marks after the path or URL.

The rendered output looks like this:

![High angle photo of assorted-colour plastic balls.](/assets/post-image.jpg 'Photo by Greyson Joralemon')

High angle photo of assorted-colour plastic balls. — Photo by Greyson Joralemon

Linking images

To add a link to an image, enclose the Markdown for the image in brackets, and then add the link in parentheses.

[![A stylised crown icon.](/assets/rebrand/images/govuk-icon-180.png)](https://www.gov.uk)

The rendered output looks like this:

Tables

To add a table, use 3 or more hyphens (---) to create each column’s header, and use pipes (|) to separate each column.

| Syntax    | Description |
| --------- | ----------- |
| Header    | Title       |
| Paragraph | Text        |

The rendered output looks like this:

Syntax	Description
Header	Title
Paragraph	Text

Cell widths can vary, as shown below. The rendered output will look the same.

| Syntax | Description |
| --- | ----------- |
| Header | Title |
| Paragraph | Text |

Alignment

You can align text in the columns to the left, right, or center by adding a colon (:) to the left, right, or on both side of the hyphens within the header row.

| Syntax    | Description | Test Text   |
| :-------- | :---------: | ----------: |
| Header    | Title       | Here’s this |
| Paragraph | Text        | And more    |

The rendered output looks like this:

Syntax	Description	Test Text
Header	Title	Here’s this
Paragraph	Text	And more

Footnotes

Footnotes allow you to add notes and references without cluttering the body of the document.

When you create a footnote, a superscript number with a link appears where you added the footnote reference. Readers can click the link to jump to the content of the footnote at the bottom of the page.

To create a footnote reference, add a caret and an identifier inside brackets ([^1]).

Identifiers can be numbers or words, but they can’t contain spaces or tabs. Identifiers correlate the footnote reference with the footnote itself — in the output, footnotes get numbered sequentially.

Add the footnote using another caret and number inside brackets with a colon and text ([^1]: My footnote.).

You don’t have to put footnotes at the end of the document. You can put them anywhere except inside other elements like lists, blockquotes, and tables.

Here’s a simple footnote,[^1] and here’s a longer one.[^longer]

[^1]: This is the first footnote.

[^longer]: Here’s the second, which has 2 paragraphs.

    Indent any following paragraphs to include them in the footnote.

The rendered output looks like this:

Here’s a simple footnote,¹ and here’s a longer one.²

Typographic replacements

Description	Text	Rendered output
En dash	`--`	–
Em dash	`---`	—
Ellipsis	`...`	…
Single quotes	`'single'`	‘single’
Double quotes	`"double"`	“double”
Simple fractions	`1/2 1/3 2/3 1/4 3/4`	½ ⅓ ⅔ ¼ ¾
Multiplication	`2 x 3`	2 × 3
Greater than	`2 => 1`	2 ≥ 1
Less than	`1 <= 2`	1 ≤ 2
Plus-minus	`2.4 +-1`	2.4 ±1
Guillemets	`<<Bonjour!>>`	«Bonjour!»
Copyright	`(C)` `(c)`	©
Registered trademark	`(R)` `(r)`	®
Trademark	`(TM)` `(tm)`	™

Paragraphs and line breaks

Headings

Heading level 1

Heading level 2

Heading level 3

Heading level 4

Heading level 5

Heading level 6

Horizontal rules

Blockquotes

Blockquotes with multiple paragraphs

Blockquotes with attribution

Alerts

Note: Check the MOT status of a vehicle

Lists

Ordered lists

Unordered lists

Nesting different list types

Starting unordered list items with numbers

Description lists

Contents list

Code

Code spans

Code blocks

Syntax highlighting

Emphasised text

Strongly emphasised text

Deleted text

Inserted text

Highlighted text

Subscript and superscript text

Links

URLs and email addresses

Formatting links

Images

Linking images

Tables

Alignment

Footnotes

Typographic replacements