How to publish on GOV.UK - Creating and updating pages - Guidance

You can preview the body copy of your document in several ways.

Preview toggle

For quick checks, like seeing if your Markdown is correct, you can use the preview toggle.

Click ‘Preview’ at the top of your ‘Body’ text box. This will show you how your text will look when published.
Review your content and formatting.
Click ‘Back to edit’ to return to your work.

The toggle button just shows you how text has been formatted. It does not save your work.

Preview entire document

You also can check how a document will appear when published on GOV.UK. You can either:

save your document by clicking the ‘Save’ button and selecting the ‘Preview on website’ link
save your document by clicking the ‘Save and go to document summary’ button and selecting the ‘Preview on website’ link

Previews for stakeholders or policy teams

There are two ways to share previews of documents with people who do not have access to Whitehall publisher. You can either:

send the document preview link to someone so they can see how it will appear on GOV.UK
use fact check to share the document and get comments

Using document preview links

Document preview links are available for:

news articles
speeches
case studies
detailed guides
publications
consultations
document collections
statistical datasets
corporate information pages

To get a document preview link:

Save your document by clicking the ‘Save and go to document summary’ button (not the ‘Save’ button).
Under the ‘Preview’ heading, click the ‘Share document preview’ dropdown.
Click ‘Copy link’ to copy the link.

You’re responsible for who you share draft documents with. The preview link will only work for the page you’re previewing.

The preview link will expire after 30 days or when the document is published. Whitehall publisher will say when the link will expire.

You can reset and generate a new preview link if you’ve shared the link with the wrong person or the link has expired. The previous preview link will be disabled. To do this:

Select ‘Generate new link’ - you’ll get a confirmation saying a new link has been generated
Select ‘Copy link’ to copy and get your new preview link.

You need to format certain documents before publishing them as attachments on GOV.UK.

Formatting CSV files for preview

Comma-separated values (CSV) files can be previewed on GOV.UK if you format them correctly. The preview will show the first 1,000 rows and 50 columns.

The CSV file should:

be tabular
have a maximum of one heading row or no header row
have no unnecessary blank lines or empty rows
be exported as a .csv with UTF-8 encoding

Select ‘view online’ to see a good example of a CSV file in preview.

Creating OpenDocument forms with simple formatting

To build a form or a document which needs to be edited, you need to publish it in .odt.

If you have access to proprietary software, such as Microsoft Office, use it to create your source document then convert to an OpenDocument (.odt).

Creating a form using .odt format has limits. You will not be able to add graphics or complicated steps in your form. If your form is complex, you could build it as a service instead.

Give users clear instructions

You can include simple instructions in your form. Clear labels on form fields will help the user follow instructions. The simpler you can make your form, the fewer instructions you’ll need.

If your form requires a lot of instructions, create them in a separate HTML publication. In Whitehall, you can do this with the publication document type.

Avoid certain elements

It is best to remove as much formatting as possible in an .odt form.

The .odt format does not have radio buttons. Use tick boxes instead.

A table with multiple columns can be difficult to navigate in any format. When a user is zoomed in, it’s often difficult to see if you have a ‘two question, two answer column’ format. Build your forms in a normal reading layout, with one column for questions on the left and one for answers on the right to avoid this problem.

You should not use nested tick boxes because they can create access problems for screen reading software. Make your tick boxes into a list or redesign the question to avoid this problem.

Do not use macros

Macros are sets of actions in a document or spreadsheet that can be automated and repeated.

You should not use macros in attachments because there are:

security issues with macros
accessibility issues with macros - an attachment containing a macro cannot be saved as an .odt file

Read guidance about alternatives to using macros on the National Cyber Security Centre website (see ‘tip 2’).

Make lists manually

You should add the numbers manually in a list as automatic listing will add more numbers as users add their answers. You can stop your editing software from creating automatic lists by clearing formatting, and then typing in the number you need.

Example of an OpenDocument form

View a good example of an .odt form with simple formatting (ODT, 7KB).

You need to save your page before adding any attachments. You can then add them individually or bulk-upload a zip file containing multiple files.

You must upload any attachments in an open standards format. For example:

.odt (OpenDocument Text) for text documents
.ods (OpenDocument Spreadsheet) for spreadsheets
.odp (OpenDocument Presentation) for presentation slides
.csv (Comma-separated values) for datasets designed to be machine-readable
.pdf (Portable document format) saved as PDF/A for fixed layout documents

You must publish an accessible version alongside a PDF - either HTML or OpenDocument.

Most publishing software will allow you to select an open format from the Save As or Download menu.

Do not use closed formats like .docx or .xlsx.

It’s possible to upload these file types:

.chm
.csv
.diff
.doc
.docx
.dot
.dxf
.eps
.gif
.gml
.ics
.jpg
.kml
.odp
.ods
.odt
.pdf
.png
.ppt
.pptx
.ps
.rdf
.ris
.rtf
.sch
.txt
.vcf
.wsdl
.xls
.xlsm
.xlsx
.xlt
.xml
.xsd
.xslt
.zip

Attachment file names

Give all files you upload a meaningful file name. Do not use vague file names, for example, v62.pdf or application-form.pdf.

A good file name will make sense to the user if they find it in their download folder. It also makes it easier to analyse data in Google Analytics.

The file name must:

be written entirely in lowercase
use hyphens or underscores instead of spaces
make sense out of context, for example, v62-application-vehicle-registration-certificate.pdf

The file name must not include:

a version number, ‘draft’, ‘clean’ or ‘final’, unless those words are part of the document title
a date, unless the date is part of the document title, for example, a business plan for 2016 to 2017

Adding a file attachment

On a saved document, go to the ‘Attachments’ tab by either selecting ‘Edit draft’, or selecting ‘Add attachments’ or ‘Modify attachments’ on the edition summary page.
Click on ‘Upload new file attachment’.
Fill in the title. If you’re adding a document or publication, use its official title.
Fill in the rest of the fields, if relevant. These ‘metadata’ fields are searchable and may help users find your document (for example, reference numbers for Freedom of Information requests).
Click the ‘Choose file’ button to find and select your attachment.
Leave the ‘Attachment is accessible’ box unticked. Even if your attachment is accessible, a user may need it in a different format like easy read.
Upload additional documents by repeating this process.

Bulk upload attachments

To upload files in bulk, you need a Zip file containing all the documents you want to attach.

On a saved document, go to the ‘Attachments’ tab by either selecting ‘Edit draft’, or selecting ‘Add attachments’ or ‘Modify attachments’ on the edition summary page.
Click on ‘Bulk upload from Zip file’.
Click the ‘Choose file’ button to find and select your Zip file.
Fill in the titles for all uploaded files. If you’re adding a documents or publications, use their official titles.
Fill in the rest of the fields, if relevant. These ‘metadata’ fields are searchable and may help users find your documents (for example, reference numbers for FOI requests).

The bulk uploader can also be used to quickly overwrite previous versions of files. If doing this, make sure your new files have the same filenames as your old ones.

Adding an external publication

On a saved document, go to the ‘Attachments’ tab by either selecting ‘Edit draft’, or selecting ‘Add attachments’ or ‘Modify attachments’ on the edition summary page.
Select the ‘Add new external attachment’ option.
Enter the attachment title and URL.

Order and position attachments

On a saved document, go to the ‘Attachments’ tab by either selecting ‘Edit draft’, or selecting ‘Add attachments’ or ‘Modify attachments’ on the edition summary page.
Click ‘Reorder attachments’ under the ‘Attachments’ heading.
Use the up and down buttons to reorder attachments, or select and hold on an attachment to reorder using drag and drop.
Select ‘Update order’ at the bottom of the page.

Publications and consultations

Attachments will automatically appear below the summary and above the body copy. They cannot be positioned within the body copy itself.

News stories, corporate groups, groups

Attachments can be positioned anywhere in the text using Markdown for attachments. You can re-position them by moving this Markdown code.

There’s content on GOV.UK to do with the government’s process of policy formation. It’s useful for users to understand the context of this content, which includes whether a previous government was in place when it was published.

For this content, users will see a message telling them the content is from a previous government.

We call this ‘history mode’. You can see an example of how this looks.

Content from previous governments will appear less prominently in internal search results unless it’s clear that’s what the user is looking for. This is because users most often want information from the current government.

This allows users to find out what a government said and did, even if there’s a change of government.

What content gets history mode

GOV.UK only displays the message on relevant formats where the ‘first published’ date is from a previous government.

It displays the message if either:

the content type and any organisations tagged are mostly associated with government policy
you associated it with a minister when you first published it

History mode displays on the following content types:

consultations
calls for evidence
corporate or annual reports
government responses
impact assessments
news stories
policy papers
press releases
speeches

You can also put history mode on collections but in most cases this needs to be done manually.

History mode will appear on some other content types if you’ve associated them with a minister. For this to happen, you need to associate them with a minister when you first publish the content. It applies to the following:

case studies
correspondence
decision
forms
FOI releases
guidance
independent reports
international treaties
maps
notices
promotional material
regulations
statutory guidance
transparency data

What content does not get history mode

History mode does not appear on:

accredited official statistics
detailed guides
fatality notices
manuals
official statistics
services and information (‘mainstream’) content

If you want history mode changed or turned off

You can contact GDS.

GDS can change the ‘associated government’ of content in history mode, if the content was actually first published under a different government.

GDS can also turn off history mode if you need to:

fix an error like a broken link or a typo - they will turn history mode back on when you’re done
add a response to a consultation or a call for evidence - if it’s a response from a new government, history mode can be kept off

GDS will not turn off history mode if you only want to update the content to keep it current.

If you have content in history mode that’s still current, consider if it should be in a different content type that will not go into history mode.

For example, if it has current guidance for users, consider the ‘detailed guide’, ‘publication: guidance’ and ‘publication: statutory guidance’ content types. You could then either:

create a brand new version of some or all of the content, with a clear explanation that it’s an updated version of the content in history mode, and ask GDS to withdraw the content in history mode
ask GDS to change the existing content into the new content type, if you chose the wrong content type initially

If you need to add new attachments to content in history mode, consider creating a new ‘document collection’. You could then create separate publications for the new attachments and group the old and new content together in the document collection.

GDS can also remove an associated minister, if they should not be associated and that’s what is putting the content into history mode.

See all content that has history mode

Export a .CSV file of the content you want to check. It will have a column saying if the content has history mode applied.

On the ‘new document’ menu, select ‘document collection’.
Write the title and summary in a way that will explain the reason for the collection to a user who sees it in search results.
Write a sentence or 2 in the ‘Body’ section to introduce the list of documents. Do not repeat the summary.
Add relevant associations.
Select ‘Save’.
Select the ‘Collections’ tab. This is where you add documents.

Add content items to a collection

You can add a document by either the title or the full URL of the document.

To add a document by the title:

Select ‘View’ next to the collection you want to add a document.
Select ‘Add document’.
Select ‘By title’.
Enter a full or partial title of the document.
Either select the ‘Enter’ button on your keyboard or select the magnifying glass.
You can select ‘View’ to check the document or select ‘Add’ to add the document to the group.

To add a document by the URL:

Select ‘View’ next to the collection you want to add a document.
Select ‘Add document’.
Select ‘By URL’.
Enter the full URL of the page.
Select ‘Add’.

Re-order documents

From the document collection tab, select ‘Reorder document’.
Use the ‘Up’ and ‘Down’ buttons to reorder one place or select and drag the button to move it up or down multiple places.
Select ‘Save’.

How to group and edit document collections

You can organise content by listing them under different subheadings, or ‘collections’.

The default name of the first collection group is ‘Collection’. To change the name:

Go to the ‘Collections’ tab.
Select ‘View’.
Select the ‘Group details’ tab.
Select the ‘Edit’ link.
Enter the new name in the name field.
You can enter a description of this group in the ‘Description’ field.
Select ‘Save’.

To add a new collection group

Select ‘Add group’.
Enter the name of the new collection in the ‘Name’ field.
You can add a description of the collection in the ‘Description’ field.
Select ‘Save’.

To reorder collection groups

Select ‘Reorder group’.
To move one place, select the ‘Up’ or ‘Down’ button. To move multiple places, select the button and drag it to its new position.
Select ‘Save’.

Add topic taxonomy tags

Select the ‘Document’ tab.
Select ‘Save and go to document summary page’.
Select ‘Add tags’ under ‘Topic taxonomy tags’.
Select the relevant tags. You can either search or select to expand its subtopics.
Select ‘Save’.

Preview a collection

From the ‘Document collections’ page, select the ‘Document’ tab.
Select ‘Save and go to document summary’.
Select the ‘Preview on website (opens in new tab)’ link.This will show you how the collection will appear when published on GOV.UK.
If you need to share the preview with someone who does not have access to Signon, use the ‘Share document preview’ link.

Withdrawn content items in a collection

When you withdraw a content item, it will disappear from any document collections it’s in. If this leaves you with an empty collection page, you’ll need to assess if any remaining content in the summary or body text needs adding elsewhere, and then unpublish the page.

The National Archives website explains the different types of official document (also known as ‘parliamentary papers’), such as command, House of Commons, and unnumbered act papers.

Official documents on GOV.UK appear in the official documents search tool. If your document does not appear in the search, you need to edit it and publish it with all the correct fields as explained below.

You can read guidance on how to write and format official documents before you publish them.

Publish an official document

Before you start, you should create different versions of the document, including:

an HTML version
web and print PDF versions – The National Archives has advice on producing ‘web-optimised’ and ‘print-ready’ PDFs in its guidance on planning papers

Choose the publication type for the document you’re publishing – for example, a policy paper or an annual report.
Complete the necessary fields.
Select ‘Save’.
Select the attachments tab, then upload the different versions. List the web PDF and HTML versions first. To upload each version:

choose ‘Upload new file attachment’ or ‘Add new HTML attachment’
fill in the title field with the name of the document
if it’s a print PDF, add ‘(print-ready PDF)’ after the title

Then fill in the rest of the fields according to the type of official document it is.

Command papers

Fill in these fields:

ISBN
Unique reference - the departmental unique reference number (URN), if the document has been given one
Command paper number - write ‘CP’ followed by the number found on the title page of the document, for example ‘CP 57’

If there’s no command paper number, tick the box labelled ‘Unnumbered’.

House of Commons papers

Fill in these fields:

ISBN
Unique reference - the departmental unique reference number (URN), if the document has been given one
House of Commons paper number - write the number found on the title page of the document, but do not include ‘HC’ as this will be added automatically
Parliamentary session - select the correct session from the drop down menu, if you’re not sure which session it is you can check the Parliamentary session calendar on the UK Parliament website

Unnumbered act papers

Fill in these fields:

ISBN
Unique reference - the departmental unique reference number (URN), if the document has been given one
House of Commons paper number - leave the field blank and tick the box labelled ‘Unnumbered’

Upload your attachment if you’re adding a PDF, otherwise add your markdown to the ‘Body’ field and click ‘Save’.

Cookies on GOV.UK

Creating and updating pages

Create and update pages, Show

Create a new document, Show

Set review date, Show

Limit access

Preview content, Show

Preview toggle

Preview entire document

Previews for stakeholders or policy teams

Using document preview links

Edit an existing (published) document, Show

Change notes

Internal notes

Formatting attachments, Show

Formatting CSV files for preview

Creating OpenDocument forms with simple formatting

Give users clear instructions

Avoid certain elements

Do not use macros

Make lists manually

Example of an OpenDocument form

Adding attachments, Show

Attachment file names

Adding a file attachment

Bulk upload attachments

Adding an external publication

Order and position attachments

Publications and consultations

News stories, corporate groups, groups

Replace, edit and delete attachments, Show

HTML documents, Show

Add topic tagging, Show

How to choose topic tags

How to tag content

Add associations (tagging), Show

Mandatory tags

Optional tags

Add contact details, Show

Add a directory contact

Content associated with the government of the time (‘history mode’), Show

What content gets history mode

What content does not get history mode

If you want history mode changed or turned off

See all content that has history mode

Schedule publishing, Show

Unscheduling

Create a collection, Show

Add content items to a collection

Re-order documents

How to group and edit document collections

Add topic taxonomy tags

Preview a collection

Withdrawn content items in a collection

Official documents, Show

Publish an official document

Command papers

House of Commons papers

Unnumbered act papers

Transparency documents, Show

Statistics, Show

Featured documents, Show

Corporate information, Show

Groups, Show

Worldwide, Show

Is this page useful?

Help us improve GOV.UK

Help us improve GOV.UK