Package 'govukhugo'

Build a Hugo site

Description

build_hugo() Hugo-ifies Rmd files and then calls Hugo to build the static site.

Usage

build_hugo(with_rmd = TRUE, rmd_folder = "R/Rmd", rebuild = FALSE)

Arguments

with_rmd	logical flag for whether to build Rmd files
rmd_folder	path to the folder containing Rmd files
rebuild	whether to rebuild all files

---

Bulk Hugo-ify Rmd files

Description

build_hugo_rmd() converts all Rmd files within a folder to Hugo-ified HTML, it will place the Hugo-ified HTML files into the content sections designated in the Rmd YAML front matter. Use render_rmd() if you want to override this. By default it expects Rmd files in the R/Rmd folder. The default behaviour is to only build files that are changed, which is tracked using the rmd.log file that is created/stored in the rmd_folder, you can force the building of all pages by setting rebuild = TRUE. If working in RStudio the process will save all open source editors windows before running.

Usage

build_hugo_rmd(rmd_folder = "R/Rmd", rebuild = FALSE, save = TRUE)

govukhugo_knit(input, ...)

Arguments

rmd_folder	path to the folder containing Rmd files
rebuild	whether to rebuild all Rmd files
save	whether to save open RStudio source files before build
input	recieved Rmd file
...	knitr fluff

Functions

• govukhugo_knit: Don't directly knit govukhugo documents

---

Clear crosstalk filters

Description

Insert a "clear filters" option to a set of filter controls. This adds an HTML div element that works with jQuery in govukhugo to clear crosstalk filters on a page, note that this clears all filters on a page including any DT search boxes.

Usage

clear_filters(text = "Clear filters")

Arguments

text	The text to display (defaults to "Clear filters")

---

Get the right data directory

Description

The govukhugo package assumes data is stored in R/data, when processing Rmarkdown files this folder is copied to a temporary folder. This is a helper function to easily work both interactively when editing an Rmarkdown file and when running the build_hugo_rmd() function.

Usage

data_dir(alt_path = NULL)

Arguments

alt_path

a non-standard location

Value

the location of the data folder

---

Use GOV.UK colours

Description

Access the GOV.UK design system colour palette

Usage

govuk_colours

govuk_palette(pal = "categorical")

Arguments

pal	One of categorical (the default), blue, blrd, bldrd_dark, blyl, putq, or a colour name from govuk_colours

Format

An object of class character of length 34.

Details

The GOV.UK design system includes a colour palette, these can be accessed via the govuk_colours vector, it includes both Sass variable colour names (e.g. govuk-text-colour) as well as the named colour palette.

The GOV.UK colour scheme was not designed with data visualisation in mind. The govuk_palette function provides an opinionated selection of GOV.UK colours for use in charts (e.g. via ggplot2::scale_fill_manual()).

The categorical palette (the default) provides an opinonated set of six GOV.UK colours for use in categorical/qualitative palettes.

The blues palette orders the GOV.UK colour palettes blues from dark to light and can be used for sequential colour palettes. Alternatively you can supply a name from the govuk_colours vector to generate the end-points for a sequential palette using that colour (where the lightest colour is roughly a third lighter than the input colour).

There are also four opinionated palettes for use in a divergent scale, these all use an off-white (the mid-colour between GOV.UK light grey and white)

• blrd which use GOV.UK blue and GOV.UK red as its end-points

• blrd_dark which uses GOV.UK dark blue as its blue end-point and a darker red of the same hue as GOV.UK red as its red end-point

• blyl which uses GOV.UK blue and GOV.UK yellow as its end-points

• putq which uses GOV.UK purple and GOV.UK turquoise as its end-points

The categorical and divergent palettes have been checked for general support for users with colour blindness.

Value

A set of hexadecimal colours

Functions

• govuk_colours: GOV.UK colour palette

---

datatables for GOV.UK

Description

govuk_datatable is a wrapper for DT::datatable() that will enable the govuk-hugo theme to apply GOV.UK CSS classes to the output.

Usage

govuk_datatable(
  data,
  title = NULL,
  element_id = NULL,
  col_names = NULL,
  page_length = 10,
  search = FALSE,
  small_text = FALSE,
  buttons = TRUE,
  col_defs = NULL,
  copy_info = NULL,
  export_file = NULL,
  options = NULL
)

Arguments

data	the data frame to display
title	a title/caption for the table
element_id	optionally, an id for the resulting HTML chunk
col_names	optionally, a vector of column names, otherwise the names of the data object
page_length	the number of rows to show per page, default is 10
search	whether to include the search box
small_text	whether to render the table content with a smaller font
buttons	whether to include copy and download buttons
col_defs	optionally, a list of column definitions
copy_info	information to include when copying the file
export_file	the file name for the exported csv
options	optionally, a list of additional options to pass to DT::datatable()

---

Initiate a Hugo site using the govuk-hugo theme

Description

init_govuk_hugo() calls Hugo to create a new site scaffold, and adds govuk-hugo as a theme. Note that this function only works inside of RStudio with an RStudio project. It is recommended that your project also uses git for version control.

Usage

init_govuk_hugo()

---

Open a new editor with the Rmarkdown skeleton

Description

The govukhugo package includes a skeleton Rmarkdown file, which can be easily selected via the RStudio GUI. new_rmd() allows you to open a new RStudio editor with a copy of the skeleton via the console.

Usage

new_rmd(
  title = NULL,
  date = NULL,
  section = NULL,
  weight = NULL,
  summary = NULL
)

Arguments

title	The page title
date	The page date
section	The section the page will go in
weight	The page weight
summary	A summary of the page

---

Hugo-ify an R Markdown document

Description

Hugo is largely used to convert plain markdown files into HTML, but it also supports HTML documents as input files. render_rmd() renders Rmd files using rmarkdown::html_document() and the converts the HTML to work with Hugo.

By default render_rmd() will read the YAML front-matter of an Rmd for a section parameter and use that as a sub-directory of the content folder as the output location.

Usage

render_rmd(rmd_file, tmp_dir = tempdir(), out_dir = NULL, quiet = TRUE)

Arguments

rmd_file	the .rmd file to convert
tmp_dir	a temporary directory for processing
out_dir	override the default output directory
quiet	keep knitr quiet, defaults to TRUE, set to FALSE to see knitr messages

---

Render ggplot2 objects as in-line SVG

Description

render_svg() converts ggplot2 objects to SVG code to render them as in-line SVG code, and provides options for providing ARIA labels for assistive technologies.

Usage

render_svg(
  plot,
  width,
  height,
  units = "px",
  alt_title = NULL,
  alt_desc = NULL,
  caption = NULL,
  dpi = 96
)

Arguments

plot	A ggplot2::ggplot() object
width	The desired width of the object
height	The desired height of the object
units	The units of width and height, default is px (pixels)
alt_title	Short alt text (will show as tool-tip)
alt_desc	Longer alt text (embedded within SVG)
caption	A caption to display to all users, can also be set to "alt_title" or "alt_desc" to match their value
dpi	Dots per inch, default of 96 for screen resolution, switch to 300 if using physical units (mm, cm or inches)

Details

When rendering to HTML, Rmarkdown will render plots as ⁠<img>⁠ tags, including when the output device is set to svg or svglite. This is problematic for accessibility reasons, as while scalable the plot continues to be rendered by the browser as an image meaning that any text within the plot is not selectable by the user and cannot be read by a screen reader.

render_svg() uses ggplot2::ggsave() to convert the plot to an chunk of SVG code, rendering text as words (via the svglite::svglite() device) and returning that code rather than producing a plot. If the alt_title, alt_desc are used then these will embedded within the SVG code, these are encoded as ARIA labels for the SVG chunk and alt_title will also present as a tooltip. Optionally, a caption can be provided which will be inserted below the plot, if the caption argument is set as alt_title or alt_desc then it will take the value of that argument.

---

Serve the site

Description

These are wrappers around blogdown::serve_site() and blogdown::stop_server(). The main purpose is to ensure that the blogdown re-knitting process doesn't run when files are saved. stop_server() is a simple re-export.

Usage

serve_site(
  build_rmd = TRUE,
  rmd_folder = "R/Rmd",
  rebuild = FALSE,
  drafts = TRUE,
  future = TRUE
)

stop_server()

Arguments

build_rmd	whether to build Rmd files before serving
rmd_folder	the folder containing Rmd files
rebuild	whether to trigger a rebuild of all Rmd files
drafts	whether to include drafts
future	whether to include pages with a date in the future

Functions

• stop_server: Stop serving a Hugo site

---

Remove bootstrap css from crosstalk components

Description

The crosstalk injects Bootstrap into rendered HTML. unstrap() removes the Bootsrap dependencies from the components.

Usage

unstrap(x)

Arguments

x	a crosstalk component, such as crosstalk::filter_select()

Value

The component x but with any "boostrap" dependency removed from its html_dependencies attribute.

Examples

# The fs object will inject css into your page.
if (requireNamespace("crosstalk", quietly = TRUE)) {
  df <- crosstalk::SharedData$new(mtcars)

  fs <- crosstalk::filter_select(
      id = "myselector",
      label = "select something",
      sharedData = df,
      group = ~cyl
    )

  # The fs_nobootstrap object won't inject css into your page.
  fs_nobootstrap <- unstrap(fs)
}

---