Quarto GOV.UK

A Quarto extension that produces HTML documents styled with the GOV.UK Design System.

Quick start

Installation

quarto use template rossbowen/quarto-govuk

This will install the extension and create an example .qmd file to get started.

Basic usage

Create a .qmd file with GOV.UK styling:

---
title: "My GOV.UK Document"
subtitle: "A subtitle that describes the document"
author: "Your Name"
date: today
format: quarto-govuk-html
---
## Introduction

Your content here following the GOV.UK Design System.

Render your document:

quarto render document.qmd

Document options

Configure your document in the YAML frontmatter:

---
title: "Document Title" # Required: Main heading
subtitle: "Brief description" # Optional: Appears under title
author: "Author Name" # Optional: Document author(s)
date: today # Optional: Publication date
date-modified: last-modified # Optional: Last update date
format: quarto-govuk-html
toc: true # Optional: Table of contents
---

Available metadata fields

Field	Description	Example
title	Main document heading	"Annual Report 2024"
subtitle	Descriptive subtitle	"Performance and outcomes"
author	Author name(s)	"Jane Smith" or ["Jane Smith", "John Doe"]
date	Publication date	today or "2024-01-15"
date-modified	Last modification	last-modified or "2024-01-20"
toc	Show table of contents	true or false

Organisation branding

Add your organisation's branding to the document header:

---
organisation:
  name: "Cabinet Office"
  colour: "#0056b8"
  crest: "org" # optional
---

Field	Description
name	Organisation name.
colour	Brand colour as hex code
crest	Crest identifier (see below)

Available crests

Crest	Image	Description
ho		Home Office
mod		Ministry of Defence
hmrc		HMRC
no10		Prime Minister's Office
portcullis		Parliament
wales		Welsh Government
org		Generic organisation
dbt		Dept for Business & Trade
ukaea		UK Atomic Energy Authority
so		Scotland Office

Example with multi-line name

organisation:
  name: "Home Office\nUK Visas and Immigration"
  colour: "#732282"
  crest: "ho"

Organisation colours

Organisation colours from the GOV.UK Frontend:

Organisation	Colour
Attorney General's Office	#a91c8e
Cabinet Office	#0056b8
Civil Service	#b2292e
Department for Business and Trade	#e52d13
Department for Culture, Media and Sport	#ed1588
Department for Education	#003764
Department for Energy Security and Net Zero	#003479
Department for Environment, Food and Rural Affairs	#00a33b
Department for Science, Innovation and Technology	#00f8f8
Department for Transport	#006853
Department for Work and Pensions	#00bcb5
Department of Health and Social Care	#00a990
Foreign, Commonwealth and Development Office	#012069
HM Government	#266ebc
HM Revenue and Customs	#008670
HM Treasury	#b2292e
Home Office	#732282
Ministry of Defence	#532a45
Ministry of Housing, Communities and Local Government	#00625e
Ministry of Justice	#000000
Northern Ireland Office	#00205c
Office of the Advocate General for Scotland	#00205c
Office of the Leader of the House of Commons	#497629
Office of the Leader of the House of Lords	#9c182f
Prime Minister's Office, 10 Downing Street	#0b0c0c
Scotland Office	#00205c
Serious Fraud Office	#82368c
UK Export Finance	#cf102d
Wales Office	#a33038

Components

This extension includes custom GOV.UK-styled components:

Masthead

The masthead appears at the top of your document with the title and subtitle:

---
title: "Your Title"
subtitle: "Your subtitle appears here"
---

Metadata box

Document metadata (authors, dates) displays in a highlighted box:

---
author: ["Author 1", "Author 2"]
date: "15 January 2024"
date-modified: "20 January 2024"
---

Figures

Images with captions following GOV.UK styling:

![This is the figure caption](images/chart.png)

Code blocks

Syntax-highlighted code with copy buttons:

```python
def hello():
    print("Hello, GOV.UK!")
```

Tables

GOV.UK-styled tables:

| Header 1 | Header 2 |
| -------- | -------- |
| Data 1   | Data 2   |

Project structure

quarto-govuk/
├── _extensions/quarto-govuk/
│   ├── stylesheets/
│   │   ├── govuk-frontend.min.css       # GOV.UK Frontend framework
│   │   ├── quarto-govuk.css             # Custom components (entry point)
│   │   ├── syntax-highlighting.css      # Code syntax theme
│   │   └── components/                  # Component-specific styles
│   │       ├── masthead.css
│   │       ├── metadata.css
│   │       ├── figure.css
│   │       ├── code-block.css
│   │       ├── line-block.css
│   │       └── lists.css
│   ├── javascripts/
│   │   └── govuk-frontend.min.js        # GOV.UK Frontend JS
│   ├── assets/                          # GOV.UK Frontend assets
│   │   ├── fonts/
│   │   ├── images/
│   │   └── rebrand/
│   ├── template.html                    # Quarto template
│   ├── filter.lua                       # Pandoc filter
│   └── _extension.yml                   # Extension config
├── update-govuk-frontend.sh             # Update automation script
└── example.qmd                          # Example document

Component naming convention

Following GOV.UK Publishing Components conventions:

• .app-c-* - Components specific to this Quarto extension
• .govuk-* - Components from GOV.UK Frontend (don't modify)

Adding custom components

1. Create a new file in _extensions/quarto-govuk/stylesheets/components/
2. Use the .app-c-your-component naming pattern
3. Import it in quarto-govuk.css:

   @import "components/your-component.css";

4. Add it to resources in filter.lua

See stylesheets/components/README.md for details.

Development

Requirements

• Quarto >= 1.3.0
• Bash shell (for update script)

Building from source

1. Clone the repository:

   git clone https://github.com/rossbowen/quarto-govuk.git
   cd quarto-govuk

2. Test the extension:

   quarto render example.qmd

3. Make your changes to components in _extensions/quarto-govuk/

4. Test your changes:

   quarto render example.qmd

Maintaining GOV.UK frontend

This extension includes automated tools to keep GOV.UK Frontend up to date.

Updating to latest version

./update-govuk-frontend.sh

Updating to specific version

./update-govuk-frontend.sh 5.13.0

What the update script does

The automated update process:

1. Fetches the latest (or specified) release from alphagov/govuk-frontend
2. Downloads and extracts release assets
3. Backs up existing GOV.UK Frontend files to .govuk-backups/ (keeps 3 most recent)
4. Installs new files:
   • CSS framework
   • JavaScript modules
   • Assets (fonts, images, icons)
5. Fixes asset paths for Quarto's structure
6. Updates source map references
7. Records version in _extensions/quarto-govuk/.govuk-frontend-version
8. Cleans up temporary files

Note: Your custom components in stylesheets/components/ are never touched by the update script.

Checking your version

cat _extensions/quarto-govuk/.govuk-frontend-version

Testing updates

Before committing updates to GOV.UK Frontend:

1. Run the update script:

   ./update-govuk-frontend.sh

2. Test with example document:

   quarto render example.qmd

3. Check the rendered output in your browser

4. If there are issues, restore from backup:

   ls .govuk-backups/
   # Manually restore files from the most recent backup

Resources

GOV.UK Design System

• Design System
• Frontend Toolkit
• Component Conventions

Quarto

• Quarto Documentation
• Creating Formats
• Lua Filters
• Pandoc Templates

License

MIT License - see LICENSE for details.

This project builds upon:

• GOV.UK Frontend - MIT License
• Quarto - GPL v2

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Example

See example.qmd for a complete example document demonstrating all features.