<!-- README.md is generated from README.Rmd. Please edit that file -->

UHHformats <img src="vignettes/images/UHHformats_logo.png" align="right" width="90" height="100" />

This R package provides ready-to-use R Markdown and now also Quarto templates for HTML, PDF and Microsoft Word output formats, which are used within the Department of Biology, University of Hamburg (German: Universität Hamburg, also referred to as UHH), and its Data Science in Biology program. The package aims to encourage reproducible research using simple Markdown syntax while embedding all of the R code to produce plots and analyses as well. Included in the package are templates for

• student assignments
  • R Markdown: Simple PDF document in English (default) or German - pdf_simple
  • Quarto: Output format for a simple PDF document in English (default) or German - pdf_simple
• project HTML files
  • R Markdown: HTML document (simple design) - html_simple
  • R Markdown: HTML document (with bootstrap design ‘Material’) - html_material
  • Quarto: Simple HTML output format - html
• PDF reports
  • R Markdown: UHH report in in English (default) or German - pdf_report
  • Quarto: Output format for a PDF report in English (default) or German - pdf_report
• cheat sheets
  • R Markdown: Output format for a simple cheat sheet (PDF) - pdf_cheatsheet
• MS Word documents
  • R Markdown: Simple Microsoft Word document - word_doc
  • Quarto: Simple Microsoft Word output format - word
• conversions from R Markdown documents to Jupyter Notebooks
  • R Markdown: Jupyter Notebook output format - rmd_to_jupyter

The default font for all templates is ‘Helvetica’ but the font can be replaced with the University’s own font style ‘TheSans UHH’ in the PDF and Word templates. If you are associated to the UHH you are allowed to use this font. Most templates include further the UHH logo and have adopted the UHH corporate design, but the logo can easily be replaced in the YAML header and also the style can be modified, by e.g. adding your own CSS stylesheet in the YAML header of the HTML template. Hence, these templates are not limited to UHH students and employees.

Many templates were developed based on other inspiring templates and R packages, which are mentioned below. To help getting started, all templates contain already some example text and code for formatting text, writing equations, creating tables and figures with cross-references and including references.

NEW in this version:

• The templates for the Bachelor and Master thesis have been moved into a separate R package named UHHthesis (see https://github.com/saskiaotto/UHHthesis/).
• Small design makeover of various templates.
• A new Word template for R Markdown was added.
• This package also contains now templates for Quarto documents that generate HTML, PDF, and MS Word output (see Quarto template gallery). Quarto is a next generation version of R Markdown from RStudio, which supports more languages and environments such as Python, Julia, or Jupyter. Like R Markdown, Quarto uses Knitr to execute R code, and is therefore able to render most existing Rmd files without modification.

Installation

NEW: The package repository has been moved to the new GitHub account of the Department of Biology, University of Hamburg: github.com/uham-bio !!!!!!

Install the development version from GitHub using the remotes package:

if (!require("remotes")) install.packages("remotes")
remotes::install_github("uham-bio/UHHformats", build_vignettes = TRUE)

Make sure that you also have the latest versions of the R packages rmarkdown and knitr installed. For some R Markdown templates you also need the R package bookdown.

if (!require("rmarkdown")) install.packages("rmarkdown")
if (!require("knitr")) install.packages("knitr")
if (!require("bookdown")) install.packages("bookdown")

If you are more interested in the Quarto templates make sure that you have the Quarto CLI on your machine installed: https://quarto.org/docs/get-started/. To render the .qmd documents directly from the console you need to have the Quarto R package installed:

if (!require("quarto")) install.packages("quarto")

Getting started

R Markdown documents

Creating a new document and rendering it within R Studio

Once you installed the package you might need to close and re-open R Studio to see the UHHformats templates listed.

1. Choose File > New File > R Markdown, then select From Template. You should then be able to create a new document from one of the package templates:

<img src="vignettes/images/img_create_document.png" alt="demo create document" style="display: block; margin: auto;" />

2. Choose the directory in which you want to save your file and provide a file name (that name will be used for both the .Rmd file and the new folder in which the .Rmd file will be placed).

3. If you are interested in the documentation already provided in the template file for getting started, render the document once before you start changing the content (click the Knit button).

Without R Studio

You can create a new directory inside your current directory, including the ready-to-use R Markdown file and all associated files (e.g. images, fonts, LaTeX templates, etc.), with the built-in function create_rmd_doc(), which is adopted from the rmdformats package.

Use, for instance,

UHHformats::create_rmd_doc(dirname = "new_doc", template = "pdf_report")

to generate a report-like PDF output.

Alternatively, use

rmarkdown::draft("new_doc.Rmd", template = "html_simple", package = "UHHformats")

These functions will automatically create the subdirectory and place the generated .Rmd file and all associated files and folders into it.

You can render your document into the HTML, PDF or Word output format using the render() function from the rmarkdown package :

setwd("./new-doc")
rmarkdown::render("new-doc.Rmd")

Important note: rmarkdown::render uses as default Pandoc to convert the Markdown document into HTML or PDF. While R Studio uses its internal Pandoc installation (e.g., on a Mac located in ‘/Applications/R Studio.app/Contents/MacOS/pandoc/’), you need to have Pandoc and its citation parser also installed on your system. See https://pandoc.org/installing.html for instructions. This book chapter is also helpful: https://bookdown.org/yihui/rmarkdown-cookbook/install-pandoc.html

Quarto documents

Quarto templates are currently not supported in RStudios IDE. Until that changes, you can access these templates with the create_quarto_doc() function. The function has three arguments: dirname for the name of the subdirectory (and .qmd file), template for the output types (choose from ‘html’, ‘pdf_simple’, ‘pdf_report’ or ‘word’) and font for the font type. If the output format is PDF or Word you can choose between the ‘Helvetica’ and ‘TheSansUHH’ font. The function will copy the .qmd files and associated files and folders into this new subdirectory

Use, for instance,

UHHformats::create_qmd_doc(dirname = "my_html_doc", template = "html")
UHHformats::create_qmd_doc(dirname = "my_pdf_doc", template = "pdf_simple", font = "TheSansUHH")

to generate a HTML page with the browsers default font or a simple PDF document with the University’s own font.

If you are using RStudio, go in the files manager to your new subdirectory, open the .qmd file and click on the Render button. For HTML output, you can use alternatively the quarto_render() function from the quarto package:

setwd("./my_html_doc")
quarto::quarto_render("my_html_doc.qmd",  output_format = "html")

Further requirements - LaTeX

In addition to Pandoc or R Studio being installed, you need to have LaTeX installed if you want to use the templates that convert R Markdown to PDF output formats. Depending on your operating systems there are different distributions you can use, e.g. for Mac there is MacTeX, which includes TeXShop, a nice Mac-only editor for .tex documents. For other OS see here: https://www.latex-project.org/get/

An easy way to install LaTeX on any platform is with the tinytex R package:

install.packages('tinytex')
tinytex::install_tinytex()
# After restarting R Studio, confirm that you have LaTeX with 
tinytex:::is_tinytex() 

TinyTeX is a custom LaTeX distribution based on TeX Live that is small in size but that includes most relevant functions (for R users). You may, however, still need to install a few extra LaTeX packages on your first attempt to knit when you use this package.

Although LaTeX is a powerful and popular tool in Academia, it can take a while to learn the syntax and to find the correct formatting. R Markdown and the PDF template in this packages offer a much simpl