In best-practice-and-impact/govspeakr: Convert standard markdown to govspeak markdown

library(knitr)
library(ggplot2)

opts_chunk$set(echo=FALSE,
               cache=FALSE,
               fig.width=960 / 72,
               fig.height=640 / 72,
               dpi=72,
               fig.path = "images/")

Introduction

This template describes how to prepare a *.md file for upload to gov.uk. Examples of syntax are displayed below, though more detailed guidance on producing md files for gov.uk can be found here.

Instructions

On its own, this template will not be able to produce the file required by publications. Knitting this R markdown template will create a html file as well as an markdown (md) file. Once the md file is produced, the user will need to run convert_md() on the md file.[^1]

It is important to recognise that the html file this template produces will not resemble the document that will appear on gov.uk. That formatting is done by the Whitehall publishing software, whose input is the md file that is produced here.

Images

Guidance on images for gov.uk publishing can be found here.

Gov.uk is very strict regarding figures. The dimensions have been defined at the top of this document, and the images will be saved in a folder called "images" within the same folder as this Rmd file is stored. Do not change the image size as this is set to that which is accepted on gov.uk.

Image filenames are also important. In markdown, filenames are created by the code chunk title that generates the image, eg, {r title}

The following code chunk creates three images that display the same data in different formats. The three image files produced within this single chunk will be named:

• 1-abc-1.png
• 1-abc-2.png
• 1-abc-3.png

df <- data.frame(x = rep(2011:2016, each = 3),
                 y = sample(1:4, 18, replace = TRUE),
                 colour = rep(LETTERS[1:3], 6))
ggplot(df, aes(x = x, y = y)) +
        geom_col(position = "dodge",
                 aes(fill = colour))

ggplot(df, aes(x = x, y = y)) +
        geom_col(position = "stack",
                 aes(fill = colour))

ggplot(df, aes(x = x, y = y)) +
        geom_col(position = "fill",
                 aes(fill = colour))

In the md file provided to Whitehall publisher, it is a requirement for the images to be inserted by typing: !!n, where n is a number refering to the order of the images (eg, !!1 is the first image, !!2 is the second image, and so on). Please title your code chunks using an increasing number sequence as the first part of the title in order for convert_md() to work. The subsequent string should have a meaningful name for the image. For example:

• 1-mortality statistics; (outputs first image)
• 2-AMR statistics; (outputs second image)
• 3-AMR by sex; (outputs third image)

Note, multiple charts produced within the same chunk (like the example above) will be detected and labelled appropriately by convert_md().

Tables

If the table doesn't have complex formatting (e.g., merged cells) then just print it within a code chunk:

library(kableExtra)
df <- data.frame(Year = rep(2014:2016, each = 2),
                 Sex = rep(c("Male", "Female", 3)),
                 Value1 = round(runif(6), 2),
                 Value2 = round(runif(6), 2),
                 Value3 = round(runif(6), 2))
kable(df, format = "markdown")

Other formatting

This template has already demonstrated bullet points and footnotes[^2].
This section covers other markdown methods:

Numbered lists {#numbered-lists}

This is how you do a numbered list:

1. Number 1
2. Number 2
3. etc

Links

Links to urls are done like this or to a particular selectable header within a page.

It is also possible to link internally to another section.

Email addresses format to links when surrounded by <>: [e-mail].

Other syntax

End a line with two spaces to start a new paragraph.

Italics, bold and strikethroughs are unsupported on gov.uk

superscript²

subscript_a,b,c

Header 1

Header 2

Header 3

Header 4

Header 5

endash: --

emdash: ---

ellipsis: ...

Block quotes/callouts should be kept to one line in the md file. If they are long enough they will split accross multiple lines automatically by the Whitehall publisher.

[^1]: The reason the md file can't be used directly as a result of knitting this document is because the code to insert an image using the Whitehall publishing software is different from traditional Markdown code. [^2]: In case you missed the first footnote reference

best-practice-and-impact/govspeakr documentation built on April 24, 2023, 1:19 p.m.