sgtemplates

R markdown templates for data analysts working for the Scottish Government. sgtemplates lets you use RStudio to quickly produce professional, accessible, Government-branded HTML documents and websites.

The design and styling of the templates is based on the Digital Scotland Design System.

Installation

Installation with Devtools

Install sgtemplates from GitHub using the devtools package. In R, copy and run the following code:

devtools::install_github("DataScienceScotland/sgtemplates")

Installation in a Restricted Environment

If you are on a restricted computer, or in a restricted network environment, you may be unable to download binaries from GitHub or use the devtools package. You can install sgtemplates manually.

Navigate to the sgtemplates repository on GitHub;
Click on the "Code" button, then select "Download ZIP" (see picture below);

Open or save the ZIP file;
Extract the ZIP file to a memorable location, keeping the folder structure;
In R, copy and run the following code:

install.packages("C:/Users/u000000/Downloads/sgtemplates-main", repos = NULL, type = "source")

Replace the example path with the path you extracted the ZIP file to.

Using the Templates

Importing Template Files into Existing Projects

sgtemplates can be easily added to your existing projects. To import the template files to your project folder:

Open your project in R;
Copy and run the following code:

sgtemplates::import_template_files()

Instruct Knitr to use the template, by adding the following argument to your YAML block:

output:
  html_document:
    template: _template.html

Creating New R Markdown Documents

sgtemplates is fully integrated into the RStudio IDE, so creating new documents and websites for the Scottish Government is easy. To create a new R markdown document in RStudio:

Select "File > New File > R Markdown";
In the new document wizard, select "From Template";
Select "Scottish Government Template";
Enter your document name and the location that your document will be saved to. Choose "OK".

Creating New R Markdown Websites

To create a new R markdown website -- multiple R markdown documents tied together by a navigation bar and a simple site structure -- in RStudio:

Select "File > New Project";
In the new project wizard, select "New Directory";
Select "Scottish Government Website";
Enter the directory that your website will be saved to. Choose "OK".

Your chosen directory will be populated with example R markdown files. It will also have a _site.yml file, which contains the configuration and metadata for your website.

For more information on authoring websites with R markdown, please read the documentation for R markdown's site generator.

Updating `sgtemplates`

After updating sgtemplates, you can also use the import_template_files() function to import the latest versions of the template files to your project folder. import_template_files() will overwrite your existing template files with the versions installed in your R library.

New Features and YAML Arguments

You can customise your documents and enable features not present in the default RStudio knitted HTML files through the use of YAML arguments. These will be fully documented in time. At present, the supported arguments can be found in the YAML block of a newly-generated sgtemplates R markdown document or website, under the parent YAML argument sgtemplates.

You do not need to use any new features. Each argument under sgtemplates can be safely deleted, if you do not want to use it.

Contact

Feedback is greatly appreciated. Please feel free to leave questions, comments, and suggestions on the GitHub discussion board. Feedback will help direct our efforts as we continue to improve and iterate on sgtemplates.

If you do not want to share feedback on GitHub, we also value feedback sent by email. Please contact either:

The Analytical Workbench support desk at analytical.workbench@gov.scot, or;
Miles Drake (project author and maintainer) at miles.drake@gov.scot.

Contributing

Please feel free to add issues, or open pull requests on GitHub.

License

This repository is publicly available under the GNU General Public License v3.0. It includes a modified version of DataTables, which is publicly available under the MIT license.

Any content produced using sgtemplates is assumed to be publicly available under the Open Government Licence v3.0, except for graphic assets and where otherwise stated. © Crown Copyright.

ScotGovAnalysis/sgtemplates