Published on
Originally published by
X-GOVUK

Write documentation using Markdown and publish it using GOV.UK styles

The homepage illustration for the GOV.UK Eleventy Plugin.

Back in 2018, the Becoming a teacher team at the Department for Education wanted to document the design evolution of the services they were building. A small website was built using the GOV.UK Prototype Kit, but this soon became difficult to manage as more people joined the team and wanted to write posts.

Looking for alternatives, the team chose Eleventy, a static website generator developed by Zach Leatherman1. Like the Prototype Kit, it uses Node.js, yet is designed around organising and publishing content-focused websites.

This includes support for Markdown, a lightweight markup language for formatting plain text documents. Posts can incorporate metadata like publication dates and authors, and be organised into different collections.

With this foundation in place, the design history grew to over 500 posts written by more than 20 authors. In 2020 we made this tool available as a template repository on GitHub so that other teams could quickly begin writing their own design histories. The tool has since been adopted by other teams, both inside the Department for Education and across government.

However, as the number of websites using this template has grown, the harder it has become to share improvements. Abstracting the common parts into an npm module makes it easier for us to do this.

A plugin for Eleventy

The GOV.UK Eleventy Plugin makes it easy to start writing documentation rather than spend time building a website for it.

It does this by providing a set of layouts for different content types and uses typography classes from the GOV.UK Design System to ensure documents look familiar to users of other GOV.UK services. (This is achieved via a plugin for markdown-it, which can be used on other projects if desired).

Markdown written using an extended syntax is also supported, meaning authors can easily include tables, abbreviations, footnotes and code examples in their posts, too.

Knowing that teams often need to write documentation for internal users, or build websites that don’t meet the criteria for using the GOV.UK logo and GDS Transport typeface, the plugin enables the following to be customised:

  • Organisation name and logo
  • Font family
  • Brand colour
  • Licence and copyright information
  • Site icons and Open Graph share images
Examples of customised websites using the plugin.
Examples of customised websites using the plugin.

Get started

The plugin is already being used by different teams across government who have built marketing pages, blogs, glossaries – and design histories, of course.

One of the benefits of static websites is they don’t need a database, which means they can be hosted pretty much anywhere. Popular platforms for hosting static websites include GitHub Pages and Netlify.

Get started with the plugin by following the instructions on the documentation website. This project is open source and contributions are welcome. If you come across an issue or have an idea for a feature, please submit an issue. We’re excited to see how you use this tool.


Footnotes

  1. If you’re wondering, the possum tied to a red balloon is Eleventy’s mascot. The illustration is by Geri Coady. ↩︎

Categories