Before you create or edit content, you need to read the style guide and understand:

• how to write for GOV.UK
• content types (formats) and how to use them

1. Select the ‘New document’ tab in Whitehall publisher.

2. Select the document type you want to create and click the ‘Next’ button.

3. If the document has a number of sub-types (for example, publications, news articles, guidance and speeches), select the relevant one from the dropdown menu at the top of the page.

4. Complete the ‘Title’ field using a maximum of 65 characters. Titles must be unique and cannot be changed once published. Titles do not need a full stop. When you save your document this will become its ‘slug’, which users will see as the last section of the page URL.

5. Complete the ‘Summary’ field using a maximum of 160 characters. This must be written as a complete sentence with a full stop.

6. Complete the ‘Body’ section using Markdown to format things like headings, bullets and links. You can paste formatted text from a document into the ‘Body’ section and it’ll be converted into Markdown. Common Markdown commands are also listed on the right-hand side of the page.

7. Below the ‘Body’ section, there are different fields you can fill in depending on the content type you’re creating. For example, you’ll usually need to add associations.

8. Before you save, you can also set a review date and limit access to the draft document. You can also schedule publication of the document for a specific date and time.

9. Save your document by either clicking ‘Save’ (which keeps you on the edit document page) or ‘Save and go to document summary’ (where you can add topic taxonomy tags).

Once a document has been saved, you can add attachments.

If you do not want to save your document, click the ‘cancel’ link at the bottom of the page. This will delete your draft and there will be no record of your document in Whitehall publisher.

You can set an optional review date if you need to maintain your content over time. On the date of review, you’ll be sent an email notification to check the content. You can then update the content or set a new review date.

Limit access

You can limit access to documents so that they can only be edited and published by editors in the department it’s tagged to. Once published it can be accessed by all editors.

Only limit access if the information is confidential.

You cannot sync limited access documents between the Production and Integration environments.

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.

1. Click ‘Preview’ at the top of your ‘Body’ text box. This will show you how your text will look when published.

2. Review your content and formatting.

3. 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:

1. Save your document by clicking the ‘Save and go to document summary’ button (not the ‘Save’ button).

2. Under the ‘Preview’ heading, click the ‘Share document preview’ dropdown.

3. 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:

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

1. Select the ‘Documents’ tab and search for the document you want to edit. Click ‘View’ next to the document title to go to the edition summary page.

2. Click ‘Create new edition’ to start a new draft version of your document for editing.

If a draft has already been created, select the ‘Go to draft’ link in the sidebar on the edition summary page and select ‘Edit draft’ in the sidebar.

When a document is being edited, there’ll be 2 versions of it in Whitehall publisher - the live page and the new draft version.

The new draft version will overwrite the live page when it’s published.

Change notes

When you edit or change a page, you can tell users the page has changed by adding a change note. The note is viewable on the page (by selecting ‘see all updates’ or ‘full page history’) and it’s emailed to people subscribed to email updates for your content. Do not do this for minor changes like typos, broken links or style corrections.

Find out more about writing change notes.

Internal notes

Add a note so other editors can see who requested the change and why.

1. Under the ‘History’ tab, select ‘Add internal note’.

2. Complete the ‘Internal note’ field and select ‘Submit internal note’.

These notes will only be seen internally (by anyone with access to Whitehall publisher).

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

1. 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.

2. Click on ‘Upload new file attachment’.

3. Fill in the title. If you’re adding a document or publication, use its official title.

4. 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).

5. Click the ‘Choose file’ button to find and select your attachment.

6. LeaveIf theyour ‘Attachmentattachment is accessible’fully boxaccessible, unticked.tick Eventhe ifbutton yourindicating attachmentthis. isIf accessible,it’s not, users will see a userbox maywith needinformation itabout inrequesting athe differentdocument formatin likean easyalternative read.format.

7. 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.

1. 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.

2. Click on ‘Bulk upload from Zip file’.

3. Click the ‘Choose file’ button to find and select your Zip file.

4. Fill in the titles for all uploaded files. If you’re adding a documents or publications, use their official titles.

5. 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

1. 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.

2. Select the ‘Add new external attachment’ option.

3. Enter the attachment title and URL.

Order and position attachments

1. 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.

2. Click ‘Reorder attachments’ under the ‘Attachments’ heading.

3. Use the up and down buttons to reorder attachments, or select and hold on an attachment to reorder using drag and drop.

4. 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.

You can replace and edit published attachments. Go to the ‘Attachments’ tab by either:

• selecting ‘Edit draft’ from the edition summary page
• selecting ‘Modify attachments’ under the ‘Attachments’ header on the edition summary page

1. From the ‘Attachments’ tab, select ‘Edit attachment’ under the attachment you want to change.

2. Upload a new file and it will overwrite the old file at the same URL location. The Markdown for this file will stay the same so does not need to be changed.

3. Edit the title or other metadata, if necessary.

You can also delete published documents.

1. From the ‘Attachments’ tab, select ‘Delete attachment’ under the attachment you want to delete.

2. Confirm you want to delete the file. The file will be deleted immediately (no need for further saving).

An HTML publication is an attachment on a publication. It cannot be created directly from the ‘Create a document’ button.

1. Once you have created and saved a publication page, select the ‘Attachments’ tab and click on ‘Add new HTML attachment’.

2. Complete the necessary fields and use Markdown in the ‘Body’ field. The content in the ‘Body’ field will look like a web page.

3. Click ‘Save’.

You’ll need to tag content to the topic taxonomy when creating or editing a document. When you tag a content item to the topic taxonomy, it will appear on a topic page automatically. See an example of a topic page.

How to choose topic tags

Choose topic tags:

• based only on what the content is about
• from anywhere in the topic ‘tree’, not just the areas that your department uses the most

Try to choose the most low-level topics you can.

Tag your content to as many topics as are relevant - there’s no limit to the number of tags you can choose.

If your content is guidance related to the end of the transition period with the EU, add a tag to ‘transition period’.

If there’s no topic that describes what your content is about, you can suggest a new topic or a change to a topic.

How to tag content

To add tags to content:

1. Go to the edition summary page of the document you want to tag.
2. Select ‘Add tags’ under the ‘Topic taxonomy tags’ heading.
3. Select the boxes next to each topic that applies. The arrows next to each topic will expand the topic out, showing all sub-topics in that topic ‘tree’. 
4. Click ‘Save’.

Topics the document is currently tagged to are listed:

• in the box with the heading ‘Topic taxonomy tags’ on the edition summary page
• under the ‘Selected topics’ heading on the ‘Topic taxonomy tags’ page

To remove a tag, go to ‘Selected topics’ and click ‘Remove topic’ next to the one you want to remove.

Adding relevant tags to your document helps users find the GOV.UK content they’re interested in.

Mandatory tags

Depending on what type of document you’re creating, it may be mandatory to add some other tags. For example, you must add:

• at least one lead organisation (add other organisations if they share responsibility for the document)
• a speaker (for speeches)
• the nations that the document applies to (for publications, detailed guides, consultations and calls for evidence)

Optional tags

You can add other tags, including:

• ministers (only if there’s direct involvement from the minister - for example, it’s a press release about a ministerial visit, or it’s a publication and the minister wrote the foreword)
• topical events
• world locations (FCDO only)

You can add contact details to a document using your organisation’s contact directory.

All frequently used email addresses should be in the contact directory. If you need to add contact details that are not in the directory, you’ll need to create a new contact.

Add a directory contact

1. Go to ‘More’ at the top of Whitehall publisher and then click ‘Organisations’.
2. Find the organisation who owns the contact and click ‘View’ next to their name.
3. Go to the ‘Contacts’ tab and copy the Markdown code under the relevant contact.
4. Paste the Markdown code into your document. Preview your document to double-check it’s the contact you wanted.

You can also add a contact by using the Markdown for addresses.

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 - 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.

Some document types (for example, policy papers, news, speeches, consultations, publications) can be scheduled for future publication.

When you have created your document:

1. Click the ‘Schedule for publication’ checkbox - the date and time controls will appear.

2. Set the date and time for the page to go live, then save the page.

Your content will only go live as scheduled if:

• it’s force scheduled, this should only be used in emergencies
• a colleague second eyes (2i) the document more than 30 minutes before publication

Some document types cannot be scheduled (for example, people, roles, groups, topical events).

Unscheduling

Once content has been scheduled to publish, you can unschedule it in order to make changes, including when it is scheduled to go live. You’ll need to press the ‘Schedule’ button again after saving your changes.

1. On the ‘new document’ menu, select ‘document collection’.

2. 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.

3. Write a sentence or 2 in the ‘Body’ section to introduce the list of documents. Do not repeat the summary.

4. Add relevant associations.

5. Select ‘Save’.

6. 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:

1. Select ‘View’ next to the collection you want to add a document. 

2. Select ‘Add document’. 

3. Select ‘By title’.

4. Enter a full or partial title of the document. 

5. Either select the ‘Enter’ button on your keyboard or select the magnifying glass. 

6. 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:

1. Select ‘View’ next to the collection you want to add a document. 

2. Select ‘Add document’. 

3. Select ‘By URL’.

4. Enter the full URL of the page.

5. Select ‘Add’.

Re-order documents

1. From the document collection tab, select ‘Reorder document’. 

2. Use the ‘Up’ and ‘Down’ buttons to reorder one place or select and drag the button to move it up or down multiple places. 

3. 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:

1. Go to the ‘Collections’ tab.

2. Select ‘View’. 

3. Select the ‘Group details’ tab. 

4. Select the ‘Edit’ link. 

5. Enter the new name in the name field. 

6. You can enter a description of this group in the ‘Description’ field.

7. Select ‘Save’. 

To add a new collection group

1. Select ‘Add group’.

2. Enter the name of the new collection in the ‘Name’ field.

3. You can add a description of the collection in the ‘Description’ field. 

4. Select ‘Save’. 

To reorder collection groups

1. Select ‘Reorder group’. 

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

3. Select ‘Save’.

Add topic taxonomy tags

1. Select the ‘Document’ tab.

2. Select ‘Save and go to document summary page’.

3. Select ‘Add tags’ under ‘Topic taxonomy tags’.

4. Select the relevant tags. You can either search or select to expand its subtopics. 

5. Select ‘Save’.

Preview a collection

1. From the ‘Document collections’ page, select the ‘Document’ tab. 

2. Select ‘Save and go to document summary’.

3. Select the ‘Preview on website (opens in new tab)’ link.This will show you how the collection will appear when published on GOV.UK.

4. 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

1. Choose the publication type for the document you’re publishing – for example, a policy paper or an annual report.

2. Complete the necessary fields.

3. Select ‘Save’.

4. 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’.

Transparency pages are a publication sub-type, so create a publication as normal and select ‘transparency data’ in the ‘Publication type’ field.

Find out how to publish statistics announcements and publications.

Find out how to feature documents on organisation pages.

Find out how to manage organisation pages and people and roles.

Find out how to create and manage groups.

Find out how to create and manage worldwide content.