The majority of problems reported by users on the departments and policy section of GOV.UK are about bad links. In the last couple of days, we've added validation checks to make sure all links created using markdown in the departments and policy publishing tool are correctly formed. If bad links are detected in a document, you will be prevented from publishing it until they are fixed.
What's a good link?
There are three different kinds of good links in our publisher (this guidance is also found on the sidebar of the edit page):
- All documents created in the publisher - policies, publications, news, speeches, detailed guides etc - should be linked to using absolute paths from within the publisher: [link text](/government/admin/policies/3373)
- All content created under an organisation tab - collection pages, topics, organisations, people, roles etc - should be linked to using the full, public URLs: [link text](https://www.gov.uk/government/topics/climate-change)
- For external websites, use the full URL including http://: [link text](http://www.example.com). The link will display with an external link symbol.
What the validation checks do
When you save a draft edition of a document, the publishing software will now check any markdown syntax for inline links and identify if the link has been correctly formed.
If the link is a path, we'll perform checks to confirm that it is:
- To admin on GOV.UK
- Absolute instead of relative (i.e. starts with a /)
If the link is a URL, we'll perform checks to confirm that it:
- Starts with http:// or https:// or mailto:
- Does not contain 'whitehall-admin'
If bad links are found
If bad links are detected, it will not be possible to publish or force-publish the document until you have fixed them.
When you look at the view page of any document, there will be a warning if the document contains bad links. When you edit one of these documents, on the right hand side you will see a list of all the links detected as invalid and a suggestion of how they could be fixed.
Automatically fixing links
We will shortly be running an automatic fix for all content currently on the site, to correct the following common issues:
- Links which refer to 'whitehall-admin', either as full admin URLs or any preview URL
- Admin paths which are relative instead of absolute.
- URLs which begin 'www' rather than 'http://'
- Links which contain '@' rather than 'mailto:'
- URLs which start 'http;' rather than 'http:'
This should remove the need for a lot of the manual clean-up by publishers.
Creating inline links in markdown is admittedly confusing. We have plans to make that easier in future, by building a tool in publisher that helps you to write good links. It might work like the current contacts tool, which suggests and autocompletes contacts for you as you begin typing.
And we are working right now on a more substantial link checker, which will scan the site and find all links returning 4xx and 5xx errors.