Govdown

Govdown is an R package for creating websites and standalone HTML pages that use the GOV.UK Design System. This website is an example. Please also consider an alternative, govuk-hugo-r.

Use govdown in the same way as R Markdown, but specify output: govdown::govdown_document instead of output: html_document in the YAML metadata of the document, or in the _site.yml file of the website.

You can’t publish govdown documents on the GOV.UK website itself. Please follow the normal guidance for how to publish on GOV.UK.

Examples

These websites and documents use govdown.

Installation

You can install the released version of govdown from CRAN with: 

install.packages("govdown")

And the development version from GitHub with: 

# install.packages("devtools") # if devtools is not already installed
devtools::install_github("ukgovdatascience/govdown")

You need Pandoc version 2.0 or greater on your system to use Govdown. You can check which version you have at the R console by typing rmarkdown::pandoc_version(). Look at this GitHub issue for advice on how to obtain a more recent version of pandoc.

Shiny

If you are developing a Shiny application, then look at https://github.com/moj-analytical-services/shinyGovstyle.

Crosstalk

If you use the crosstalk package for interactive commponents, then use the govdown::unstrap() function to prevent them from interfering with how the page is rendered.

Creating standalone HTML pages

Govdown HTML pages are created in the same way as R Markdown HTML pages. Write a markdown document (a plain text file with the suffix .Rmd instead of .txt), and put something called ‘YAML metadata’ at the top. It should look like this: 

---
output:
  govdown::govdown_document:
    font: "sans-serif" # (default) or "new-transport"
    favicon: "custom" # or "none" (default) or "govuk" see ?govdown_document
    logo: "images/logo.svg" # or false (default)
    logo_url: "https://ukgovdatascience.github.io/govdown/"
    logo_text: "logo_text"
    page_title: "page_title"
    title: "title"
    phase: alpha
    feedback_url: "https://github.com/ukgovdatascience/govdown/issues"
    google_analytics: "UA-12345678-90"
---
This is a study of official statistics in the UK.

To render that file to HTML, run rmarkdown::render("filename.Rmd") in the console, or click the ‘knit’ button in RStudio.

You must use font: "sans-serif" unless the page is hosted on the gov.uk domain.

Creating websites

Websites are created in the same way as R Markdown websites. Write a set of markdown documents (plain text files with the suffix .Rmd instead of .txt), and a configuration file called _site.yml with content like the following: 

output_dir: docs # to host on GitHub pages
navbar: # links to include in the bar at the top of every page
  - text: "Home"
    href: index.html
  - text: "Tech docs"
    href: tech-docs.html
  - text: "News"
    href: NEWS.html
output:
  govdown::govdown_document:
    font: "sans-serif" # (default) or "new-transport"
    favicon: "custom" # or "none" (default) or "govuk" see ?govdown_document
    logo: "images/logo.svg" # or false (default)
    logo_url: "https://ukgovdatascience.github.io/govdown/"
    logo_text: "logo_text"
    page_title: "page_title"
    title: "title"
    phase: alpha
    feedback_url: "https://github.com/ukgovdatascience/govdown/issues"
    google_analytics: "UA-12345678-90"

That example shows all the possible configuration. You don’t have to set a logo or favicon or have any links (although you probably should eventually), and if you don’t set an alpha or beta phase banner then you won’t need a feedback_url. However you must set font: "sans-serif" unless the website is hosted on the gov.uk domain. Set output_dir: docs if you will deploy the site on GitHub pages, otherwise refer to the R Markdown documentation on publishing websites.

To render the website, run rmarkdown::render_site() in the console, or click the ‘Build Website’ button in RStudio Build panel.

Supported markdown syntax

Most of the usual markdown syntax is supported. There is some new syntax for special features of the GOV.UK Design System.

Where syntax isn’t supported, that might be because research by contributors to the GOV.UK Design System found the features to be detrimental. Govdown defers to the GOV.UK Design System in these cases.

Headings

Create headings by beginning a new line of text with a # symbol. 

# Pithy heading

Rambling content.

Subheadings have more #s 

## Helpful subheading

### Can't remember what the main topic was?

#### Four levels of headings are available!

This is a captionHeadings with captions

The GOV.UK Design System supports captions above headings. This works for headings of level 1, 2 and 3, but not for the smallest headings (level 4). 

# Heading with caption above {caption="This is a caption"}

Bold, italics and strike-through

Bold works as normal, but italics and strike-through are disabled because they are not supported by the GOV.UK Design System. 

**Bold** works as normal, but *italics* and ~~strike-through~~ are disabled.

Lead paragraphs and small text

The GOV.UK Design System supports larger and smaller text for paragraphs. Large text is for a single lead paragraph at the top of a page. See the top of this page for an example.

Small text looks like this. 

::: {.lead-para}
This is a lead paragraph that appears in larger text than the rest of the body
text of the page.
:::

This is a normal paragraph in normal size.

::: {.small-para}
You can write in small letters too.
:::

Indented text (quotations)

Indented text (often used for block quotations) works as normal.

United wishes and good will cannot overcome brute facts. Truth is incontrovertible. Panic may resent it. Ignorance may deride it. Malice may distort it. But there it is. – Winston Churchill 

> United wishes and good will cannot overcome brute facts.  Truth is
> incontrovertible. Panic may resent it. Ignorance may deride it. Malice may
> distort it. But there it is. -- Winston Churchill

Warnings

Use the Warning text when you need to warn users about something important, such as legal consequences of an action, or lack of action, that they might take.

Warning Fee fi fo fum 
::: {.warning}
Fee fi fo fum
:::

Hyperlinks work as normal. The GOV.UK Design System also supports hyperlinks that don’t change colour when you have visited the page. 

[normal hyperlink](https://design-system.service.gov.uk).

[hyperlink that doesn't turn purple](https://design-system.service.gov.uk){.no-visited-state}.

Bullets and numbered lists

Bulletted and nested lists work as normal, except that nested lists don’t look very good because they aren’t supported by the GOV.UK Design System. Govdown defers to the designers who made this decision, but if you have evidence of a need for nested lists, please submit it to the GOV.UK Design System by opening a new GitHub issue on the GOV.UK frontend repository. 

* First bullet
  * Nested bullets are available but ...
  * ... they don't look very good because the GOV.UK Design System doesn't
    really support them.
* Second bullet
* Third bullet
  1. Numbered list item
  2. Second numbered list item
  3. Third numbered list item 
1. Numbered list item
1. Second numbered list item
1. Third numbered list item

The GOV.UK Design System also supports lists with neither bullets nor numbers. Standard markdown doesn’t have any syntax for this, so create a bulletted list and wrap it with a special marker, shown below.

  • Unbulleted item one
  • Unbulleted item two
  • Unbulleted item three 
::: {.unbulleted-list}
* Unbulleted item one
* Unbulleted item two
* Unbulleted item three
:::

Section breaks

The usual section break is available. 

---

The GOV.UK Design System supports several sizes of section break; govdown uses the largest. For the other sizes use the raw HTML. 

<hr class="govuk-section-break govuk-section-break--xl govuk-section-break--visible">
<hr class="govuk-section-break govuk-section-break--l govuk-section-break--visible">
<hr class="govuk-section-break govuk-section-break--m govuk-section-break--visible">
<hr class="govuk-section-break govuk-section-break--visible">


The GOV.UK Design System uses breadcrumbs to help users know where they are on a website. They are used at the top of a page.

  1. trail
  2. of
  3. breadcrumbs 
::: {.breadcrumbs}
* [trail](index.html)
* [of](index.html)
* breadcrumbs
:::

Tabsets

Tabs can be a helpful way of letting users quickly switch between related information. See the guidance on the GOV.UK Design System.

The syntax is different from normal R Markdown tabsets. 

::: {.tabset}
# Heading appears on narrow screens

## Tab heading 1

Tab content A

## Tab heading 2

Tab content B

Second paragraph of content.
:::

Heading appears on narrow screens

Tab heading 1

Tab content A

Tab heading 2

Tab content B

Second paragraph of content.

Accordions

The accordion component lets users show and hide sections of related content on a page. See the guidance on the GOV.UK Design System.

The syntax is similar to govdown tabsets. 

::: {.accordion}
## Writing well for the web

This is the content for Writing well for the web.

## Writing well for specialists

This is the content for Writing well for specialists.

## Know your audience

This is the content for Know your audience.

## How people read

This is the content for How people read.
:::

Writing well for the web

This is the content for Writing well for the web.

Writing well for specialists

This is the content for Writing well for specialists.

Know your audience

This is the content for Know your audience.

How people read

This is the content for How people read.


Details

Details make a page easier to scan by letting users reveal more detailed information only if they need it. As with Tabs, guidance can be found on the GOV.UK Design System.

The syntax uses the summary attribute to provide the top level information with the content provided by the text within.

Warning The details component requires Pandoc version 2.5 or more recent. 
::: {.details summary="Details"}

Here are some details on the
[Government Digital Service](https://www.gov.uk/government/organisations/government-digital-service).

Multiple paragraphs can be contained in details.

:::
Details

Here are some details on the Government Digital Service.

Multiple paragraphs can be contained in details.

Code blocks

Code blocks work the same as they do in markdown and R Markdown. Code in R Markdown files (.Rmd suffix) will be evaluated, and the result interleaved below the code. 

print("This code will not be evaluated")
print("This code will be evaluated")
## [1] "This code will be evaluated"

Create code chunks that are not to be evaluated using a plain markdown R code chunk as follows. 

```r
print("This code will not be evaluated")
```

Or specify an R Markdown R code chunk with the option eval=FALSE as follows. 

```{r eval=FALSE}
print("This code will not be evaluated")
```

Create code chunks that are to be evaluated as follows (of course you can also explicitly set chunk option eval=TRUE). 

```{r}
print("This code will be evaluated")
```

Python code chunks also work (as long as you have the reticulate package and Python installed), as do any of the languages supported by knitr. For example, 

```{python}
'Monty Python'.split()
```

produces the following. 

'Monty Python'.split()
## ['Monty', 'Python']

Images

Images use the normal markdown syntax.

caption text

Or you can use the knitr::include_graphics() function in an R Markdown R code chunk.

Tables

All four kinds of pandoc tables work. Below is a common kind. Note that only left-aligned and right-aligned columns are supported in the GOV.UK Design System, and captions always appear above the table. 

Table: This is a table caption.

| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |
This is a table caption.
Right Left Default Center
12 12 12 12
123 123 123 123
1 1 1 1 
Another table without a caption.

| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |

Another table without a caption.

Right Left Default Center
12 12 12 12
123 123 123 123
1 1 1 1

Tables can also be created from code chunks. This example in R uses knitr::kable(). 

knitr::kable(head(mtcars[, 1:4]))
mpg cyl disp hp
Mazda RX4 21.0 6 160 110
Mazda RX4 Wag 21.0 6 160 110
Datsun 710 22.8 4 108 93
Hornet 4 Drive 21.4 6 258 110
Hornet Sportabout 18.7 8 360 175
Valiant 18.1 6 225 105

If kable doesn’t produce a table that looks like the one above, then try using the format argument, for example kable(mtcars, format = "markdown") or kable(mtcars, format = "pandoc"). You will need to do that if the kableExtra package is loaded, because kableExtra sets a global option. Check the value of getOption("knitr.table.format") to see if that option has been set. If kableExtra isn’t loaded, then the option might be set in your .Rprofile, which you can open with usethis::edit_r_profile().

Mathematical equations

Mathjax is supported as normal, by wrapping the equation in $ symbols (inline equations) or in $$ symbols on their own line (block equations).

Here’s some inline mathjax \(\sum_0^{2e} \alpha_i \mathrm{dt}\). Here’s some block mathjax

\[ \begin{align} s_i & \sim \mathrm{Binomial}(n_i, p_i) \\ \mathrm{logit}(p_i) & = \alpha_{\small{TANK}[i]} \\ \alpha_{\small{TANK}} & \sim \mathrm{Normal}(0, 5) \end{align} \]

Contribute to the development of govdown

Use install-govuk-frontend.sh to download, modify and compile the GOV.UK Design System to get the css files for the templates.

Prerequisites

The sassc command-line tool. If you can’t get that to work, try the sass package by RStudio, which wraps it.