Markdown
Using Markdown to format content in Whitehall publisher.
When you edit a document in Whitehall publisher you’ll also see a quick guide to Markdown under ‘Formatting’ on the right of the screen.
Acronyms
Adding acronym Markdown to a document means that when a user hovers over the acronym they see the full name as ‘alt text’.
This text has acronym Markdown applied.
You should:
- add the acronym Markdown at the end of the body copy, leaving one empty line space above it
- type an asterisk, square brackets around the acronym and a colon, then the full name, for example *[DWP]: Department for Work and Pensions
- make sure there is no space between the asterisk and the square bracket
When you have more than one acronym, list:
- each one on a new line
- both plurals and singulars, but not possessives, for example DFT’s
- plurals ahead of singulars, for example HGVs before HGV
See the style guide for how to use acronyms.
Addresses
For addresses use the Markdown $A above and below the address text.
Addresses look like this.
Example:
$A
Put the
address in
here
$A
Do not use bold for the address title. This is not accessible because it looks like a heading and can be confusing for users of assistive technology. Use heading Markdown above the address Markdown instead if you need to draw attention to the information.
Attachments
Use the Markdown for either ‘inline’ or ‘publication box’ attachments to position your attachments in the body text.
First you need to upload your attachments. The first attachment you upload is number 1, the second number 2, and so on. The number of an attachment does not change, even if previous attachments are deleted.
Inline attachment
This will add the attachment title to a sentence or bullet point as hypertext. The file type and size shows in brackets after the title.
In the text, type [InlineAttachment:n]
Publication box
This is a more prominent link than the inline attachment. It shows the cover of the attached document, and adds the file type and size under the title. You should:
- type !@1 for a publication box
- leave a line space above and below the Markdown
For more information about attachments see the creating and editing content section.
Blockquotes
Blockquote Markdown should only be used for news stories and case studies. Do not use blockquotes in speeches.
In news and case studies:
- introduce the blockquote with a colon
- leave one empty line space above and below your blockquote
- add ‘>’ in any line spaces in the quote - if you leave it out you’ll get separate quotes on separate lines, not one running quote
For more advice on using blockquotes on GOV.UK, see the style guide.
Bullets
To create a bulleted list:
- use asterisks (*) to make bullets (hyphens also work)
- make sure there is one space after the asterisk
- leave 1 empty line space before the bullets start, and one after
See the style guide to check how to punctuate bullets.
Call to action
Call to action Markdown should be used for short links to actions, like applying for a licence. It creates a tinted box which highlights the task.
To create the call to action box use the Markdown $CTA above and below the link.
$CTA
It looks like this.
$CTA
It looks like this.
Charts
Charts Markdown allows you to create ‘simple’, ‘stacked’ and ‘compact’ bar charts which can also display negative values. You can combine these within 1 chart.
The Markdown lets the user switch between a bar chart and a table view on the webpage.
Simple bar chart
You can show numeric data as a simple bar chart. Use grouped bars for multiple columns.
Stacked bar chart
You can also create stacked bars. The final column is used to display the total.
Compact bar chart
You can use a compact bar chart to save space if you have a large graph.
Negative bar chart
Use this if you have negative values in your bar chart.
Headings
In the document body, use 2 hashtags (##) for a section heading and 3 or 4 hashtags for sub-headings. These are called H2s, H3s and H4s.
Make sure you use heading level Markdown (the hashtags) rather than bold text - assistive technology lets users navigate to heading levels.
Use the headings in sequence. An H3 needs to be preceded by an H2 and an H4 needs an H3.
Do not use one hashtag, or you will get a title heading in the middle of your document.
There’s no need to use Markdown in the title and summary boxes. They are styled automatically.
There’s more guidance on headings in the content design manual.
Images
To add images to a page:
- first upload your image(s)
- add the image Markdown !!n, where ‘n’ is the number of the image, in the text at the point(s) where you want the image to show on the webpage
- leave an empty line space above and below the Markdown
Links
To add internal links to GOV.UK pages, use square brackets [] around the link text and round brackets () around the link URL. Make sure there are no spaces between the brackets or the link will not work.
Use the Whitehall publisher URL (like https://whitehall-admin.production.alphagov.co.uk/government/admin/publications/221540) when linking to any document made by the ‘create new document’ button (publications, consultations, speeches etc).
You should delete the first part of the URL and use the relative path: /government/admin/publications/221540.
Email links
Use ‘less than’ (<) and ‘greater than’ (>) arrows around email addresses to make them a link.
<example@example.com>
Linking to paragraphs
Add a markdown anchor tag if you want to link to a specific paragraph. Make sure you add it below the paragraph you want to link to, not above.
{:#heading-name}
You can link to the paragraph from the same document:
[Paragraph link text](#links)
or from another document:
[Document link text](https://www.gov.uk/government/policies/managing-freshwater-fisheries#eel-decline)
Note: you have to use the full public URL when linking to a paragraph in another document. The admin URL will not work.
The links section explains how to write and format links and includes the external linking policy.
Numbered list
-
Use numbers followed by a full stop, for example ‘1.’.
-
Make sure there is one space after the full stop.
-
You need 1 empty line space before the numbers start, and 1 at the end.
-
Sub-items need an indent of 2 spaces.
See the style guide to check how to punctuate numbered lists.
Subscript and superscript
For subscript, surround the text to change with the < sub > < /sub > markdown.
This is an example of using subscript in text.
For superscript, surround the text to change with the < sup > < /sup > markdown.
This is an example of using superscript in text.
You should use subscript and superscript for scientific notation and measurements, for example chemical names, metres squared.
Tables
To make a table you need to:
- leave one empty line space before the table starts and one at the end
- use the Markdown for ‘dividers’ (sometimes called ‘pipes’) to split the content into cells, for example:
item 1 | item 2 | item 3 - make sure every row has the same number of dividers
- make a bold header row by using hyphens between the dividers in the second row, for example:
----|----|---- - add a hash (‘#’) character after the pipe if the cell is the title of a row, for example
|# Row 1 | item 1 | item 2 | item 3
You can also use a table generator to convert an Excel document, Google sheet or web-page table to Markdown.
Aligning columns and adding links
You can use markdown to add links in a table cell, for example: |[This is a link in a cell](https://www.example.com)|.
You can also right align a column by putting a colon before the divider at the end of a cell in the second row. The ‘cost’ column will be right aligned in this example:
| item | cost |
|-----|-----:|
| bread | 75 |
| milk | 99 |
Example
| item | cost |
|---|---|
| bread | 75 |
| milk | 99 |
Find out more information about when to use tables and how to make them accessible.
Video
You can embed videos directly into your page using Markdown. Only YouTube videos will work.
You should:
- put the title of the video in square brackets and next to it in round brackets (no space) the URL of the YouTube page
- leave a line space above and below your link
Do not:
- use the embed code or the ‘Share this video’ URL
- use a bullet point
The video will display in an embedded media player automatically.
Markdown for manuals
There is some Markdown which is only to be used for the manual format.
Priority list
You can create a list which shows only the first n items (including attachments), with a link to open the others, for example to show the first item. This is the Markdown you’ll need to use:
$PriorityList:1
* item 1
* item 2
* item 3
Legislative list
This Markdown is for lists where you want to specify the numbering and have multiple indent levels:
- 1. Item 1
- 2. Item 2
- a) Item 2a
- b) Item 2b
- i. Item 2 b i
- ii. Item 2 b ii
- 3. Item 3
(to indent, add 2 spaces)
Footnotes
To include footnotes in your text you should:
- add the footnote Markdown at the end of the line which the footnote refers to
- leave 1 empty line space
- add the same footnote Markdown on the line underneath with the corresponding footnote content
- leave 1 empty line space before continuing the main text
The footnote content will always appear at the end of the document regardless of where they are in the Markdown.
Footnotes can be added using [^2] to create the footnote.
Use the Markdown followed by a colon to define the footnote: [^2]:
Footnote content can hold more than 1 paragraph by indenting the content 4 spaces.