How to create UKCEH-branded documents in Quarto/Shiny
This tutorials introduces Posit’s brand-yml theme configuration, and demonstrates how to apply UKCEH branding (fonts, colours and logos) to Quarto documents (such as this website) and Shiny apps.
1 Introduction
1.1 What is a brand.yml?
brand.yml is Posit’s attempt to develop a unified mechanism for theme configuration — logos, colours, fonts and typography — across different output formats — documents, presentations, websites, dashboards, apps — produced by Quarto or Shiny projects.
brand.yml provides a way to single-source this configuration as a plain-text YAML file. This is particularly useful for organisations such as UKCEH since the configuration can be distributed from a single, centrally managed repository on GitHub.
A GitHub-hosted brand.yml can be applied to existing projects without any modifications to the source, by ‘installing’ it as an extension. As a bonus, any changes to the theme (e.g. due to a rebranding) can be applied retroactively by simply updating the extension (essentially git pull).
1.2 What does it look like?
Visit ukceh-rse.github.io/brand-yml to see some examples of the UKCEH brand applied to some basic Quarto documents (HTML page, pdf and presentation).
2 How to use brand-yml
This will only work with Quarto version 1.8 or higher! As of 20/08/2025 this is still in pre-release, but it can be downloaded here.
This will only work for projects, i.e. when there is a _quarto.yml file containing the project field.
However, there is no real downside to upgrading stand-alone documents to projects. Simply create a _quarto.yml file with the following contents:
project:
type: default2.1 Existing projects
First, install the extension.
Run the following command in the root directory of your quarto project.
quarto add ukceh-rse/brand-ymlTo do.
This will install the extension under the _extensions subdirectory. If you’re using version control, you will want to check in this directory.
You will need to specify the desired format when you render.
quarto render --to FORMATTo do
If you plan to render to multiple formats with the same file extension you will also need to specify an output file (--output FILE) so that they don’t overwrite each other.
2.2 New projects
The extension also serves as a starter template for stand-alone Quarto documents and presentations. There are currently 5 formats provided out of the box.
htmltypsttypst-darkrevealjsrevealjs-dark
To create a new project based on this template, run the following:
quarto use template ukceh-rse/brand-ymlTo do.
2.3 Without installing an extension
An alternative is to simply download the contents of _extensions/brand/ and manually place them in your quarto project.
Rename brand.yml -> _brand.yml so that it is picked up automatically. This will also work for non-projects (no _quarto.yml).
3 FAQ
3.1 Why not use the existing templates?
We have a couple of very nice templates for UKCEH-branded powerpoint presentations and word documents.
However, people increasingly prefer to work with plain text documents, which are superior to Microsoft’s formats in a number of ways:
- Portability: can be read and edited on any device without requiring proprietary or closed-source software
- Longevity: you will be able to open, read and edit plain text files in 20 years time. Can you say the same for a Word document?
- Compatibility with version control software.
- Supports multiple output formats from a single plain text source.
- Supports blending of executable code and regular text.
Perhaps most importantly, a significant number of people with UKCEH already use Quarto, RMarkdown (its predeccessor) and Shiny already. There are already numerous official UKCEH outputs — mostly dashboards and Shiny apps — that were produced with these tools, but with the branding applied loosely or not at all.
3.2 How is this consistent with the UKCEH branding?
The logos, colours, fonts and typographic information used in brand-yml were lifted from the UKCEH Brand Book (v4.0, September 2024).
The brand book does not provide guidance on dark-themed documents, so I applied a little creative freedom here in deciding which colours to use as primary, secondary, background etc.
3.3 Has this been approved by Comms?
Short answer — no.
Longer answer — not yet. I am in contact with folk in the design team and they are on the whole positive about the whole thing. However, they have wisely suggested waiting until the ongoing rebrand has sorted itself out before pushing ahead with efforts to make this ‘official’.
3.4 Where is the UKCEH brand-yml kept?
On GitHub, at github.com/ukceh-rse/brand-yml.
The repository is currently housed under the RSE’s own GitHub organisation (github.com/ukceh-rse). Once (if) this gets approved by the Comms team for organisation-wide use, we may find that it needs to be moved to the official UKCEH GitHub organisation (github.com/NERC-CEH).
3.5 What about templates that reproduce the official Word and Powerpoint templates?
This has been on my radar for a while, and I made a start with a Quarto/RevealJS presentation template that closely aligns with the official Powerpoint template.
However, it involves a fair amount of Javascript to get working, and I’m not overly satisfied with my initial attempt.
I plan to revisit this once the rebranding is complete, which will likely result in the official document templates changing anyway.
3.6 I’ve found a bug, what do I do?
Please raise an issue on GitHub if you are able to. Otherwise get in touch with Joe directly.