Workshops for Ukraine
11 January 2024
Lecturer in Health Data Science at Lancaster Medical School.
Academic background in statistics, with experience in data science consultancy.
Blog about R and data science at nrennie.rbind.io/blog.
The workshop will run for 2 hours.
Combines slides, live coding examples, and exercises for you to participate in.
Ask questions in the chat throughout!
Working installation of Quarto, and are able to render an HTML document. If not, download from quarto.org.
Able to run command line operations e.g. via Terminal in RStudio.
Ideally, a working installation of one of R, Python, or Julia.
GitHub: github.com/nrennie/workshops-for-ukraine-quarto-extensions
Slides: nrennie.github.io/workshops-for-ukraine-quarto-extensions
Quarto is an open-source scientific and technical publishing system that allows you to combine text, images, code, plots, and tables in a fully-reproducible document. Quarto has support for multiple languages including R, Python, Julia, and Observable. It also works for a range of output formats such as PDFs, HTML documents, websites, presentations, …
Documents from different authors look the same.
Default options usually look like the default options.
Information can often be presented in better ways when designed actively.
Quarto includes 25 themes from the Bootswatch project for HTML output.
See quarto.org/docs/output-formats/html-themes.html for a complete list.
There are also 11 built-in themes for Revealjs presentations.
---
title: "My document"
format:
html:
backgroundcolor: lightblue
---
Content goes [here](https://github.com/).
See quarto.org/docs/reference/formats/html for all HTML options.
See examples/Example 1/example1.qmd
for full code.
Open exercises/Exercise 1/README.md
for prompts.
Create a Quarto document which outputs to HTML format.
Include some text and a code block (in a programming language of your choice).
Edit the YAML to use one of the Bootswatch themes. See quarto.org/docs/output-formats/html-themes.html for options.
Further edit the YAML to change the linkcolor
.
Bonus: edit other YAML options to customise further.
See exercise_solutions/Exercise 1
for full solution.
See quarto.org/docs/output-formats/ms-word-templates.html for all MS Word options.
See quarto.org/docs/reference/formats/pdf for all PDF options.
document.qmd
In the upcoming Quarto 1.4 release, you can also create PDFs using Typst (no LaTeX!).
See examples/Example 2/example2.qmd
for full code.
Open exercises/Exercise 2/README.md
for prompts.
Create a styles.scss
file.
Add the styles.scss
file to the YAML options in your Quarto file.
Create some CSS variables and write some simple CSS rules in the styles.scss
file.
See exercise_solutions/Exercise 2
for full solution.
Extensions are a powerful way to modify and extend the behavior of Quarto. Extensions can be used to add styling to your documents.
Extensions aren’t just used to change document styling.
There are also extensions to:
There are different ways to distribute Quarto extensions. Many are distributed via GitHub.
To install an extension, run the following in the command line:
For example, to install my PrettyPDF
extension:
This creates an _extensions
folder in your current directory.
You then need to edit the YAML at the top of the Quarto document, to tell it to use the extension:
Need to reformat to a completely different style?
Some Quarto extensions (especially style extensions) come with a template file that changes the YAML for you.
For example, to use my PrettyPDF
template:
This creates an _extensions
folder in your current directory and a .qmd
file with the correct YAML.
See examples/Example 3/example3.qmd
for full code.
Open exercises/Exercise 3/README.md
for prompts.
Install the LCARS
template by Michael McCarthy using quarto add mccarthy-m-g/quarto-lcars-theme
.
Edit the YAML of your .qmd
file to use the extension. See github.com/mccarthy-m-g/quarto-lcars-theme for more information.
Re-render your document.
Bonus: browse the Awesome Quarto list and choose a different extension: github.com/mcanouil/awesome-quarto
See exercise_solutions/Exercise 3
for full solution.
Don’t copy and paste commonly used YAML options between documents.
Everybody in an organisation can create similar outputs without having to adjust the style themselves.
Changes to designs can be tracked alongside code.
The essentials…
_extensions folder
_extension.yml file
The nice to haves…
template.qmd file
Other files e.g. logos or fonts
The folder structure might look like this:
template.qmd
file---
title: "Pretty PDFs with Quarto"
format: PrettyPDF-pdf
---
## Quarto
Quarto enables you to weave together content and executable code into a finished
document. To learn more about Quarto see <https://quarto.org>.
### Running Code
When you click the **Render** button a document will be generated that includes both
content and the output of embedded code. You can embed code like this:
```{r}
1 + 1
```
_extension.yml
filePrettyPDF.tex
file% load packages
\usepackage{geometry}
\usepackage{xcolor}
\usepackage{eso-pic}
\usepackage{fancyhdr}
\usepackage{sectsty}
\usepackage{fontspec}
\usepackage{titlesec}
%% Set page size with a wider right margin
\geometry{a4paper, total={170mm,257mm}, left=20mm, top=20mm, bottom=20mm, right=50mm}
%% Let's define some colours
\definecolor{light}{HTML}{E6E6FA}
\definecolor{highlight}{HTML}{800080}
\definecolor{dark}{HTML}{330033}
%% Let's add the border on the right hand side
\AddToShipoutPicture{%
\AtPageLowerLeft{%
\put(\LenToUnit{\dimexpr\paperwidth-3cm},0){%
\color{light}\rule{3cm}{\LenToUnit\paperheight}%
}%
}%
% logo
\AtPageLowerLeft{% start the bar at the bottom right of the page
\put(\LenToUnit{\dimexpr\paperwidth-2.25cm},27.2cm){% move it to the top right
\color{light}\includegraphics[width=1.5cm]{_extensions/nrennie/PrettyPDF/logo.png}
}%
}%
}
%% Style the page number
\fancypagestyle{mystyle}{
\fancyhf{}
\renewcommand\headrulewidth{0pt}
\fancyfoot[R]{\thepage}
\fancyfootoffset{3.5cm}
}
\setlength{\footskip}{20pt}
%% style the chapter/section fonts
\chapterfont{\color{dark}\fontsize{20}{16.8}\selectfont}
\sectionfont{\color{dark}\fontsize{20}{16.8}\selectfont}
\subsectionfont{\color{dark}\fontsize{14}{16.8}\selectfont}
\titleformat{\subsection}
{\sffamily\Large\bfseries}{\thesection}{1em}{}[{\titlerule[0.8pt]}]
% left align title
\makeatletter
\renewcommand{\maketitle}{\bgroup\setlength{\parindent}{0pt}
\begin{flushleft}
{\sffamily\huge\textbf{\MakeUppercase{\@title}}} \vspace{0.3cm} \newline
{\Large {\@subtitle}} \newline
\@author
\end{flushleft}\egroup
}
\makeatother
%% Use some custom fonts
\setsansfont{Ubuntu}[
Path=_extensions/nrennie/PrettyPDF/Ubuntu/,
Scale=0.9,
Extension = .ttf,
UprightFont=*-Regular,
BoldFont=*-Bold,
ItalicFont=*-Italic,
]
\setmainfont{Ubuntu}[
Path=_extensions/nrennie/PrettyPDF/Ubuntu/,
Scale=0.9,
Extension = .ttf,
UprightFont=*-Regular,
BoldFont=*-Bold,
ItalicFont=*-Italic,
]
See examples/Example 4/example4.qmd
for full code.
Open exercises/Exercise 4/README.md
for prompts.
Create an _extensions
folder in the same directory as your .qmd
file.
Create another folder inside the _extensions
for your extension e.g. PrettyHTML
.
Move your styles.scss
file from Exercise 2 into the PrettyHTML
folder.
Create an _extension.yml
file in the PrettyHTML
folder.
Write the YAML code specifying the extension title, author name, version number, and contribution (HTML format with the styles.scss
styling).
Edit the YAML in the .qmd
file to use this extension.
See exercise_solutions/Exercise 4
for full solution.
There are two ways to distribute extensions:
See quarto.org/docs/extensions/distributing.html.
Alternatively, as an R (or Python/Julia) package: github.com/jthomasmock/octavo
Things I learnt the hard way…
Things get confusing when you build an extension with same name as your GitHub username.
(Font) paths are hard.
You’ll likely want multiple output formats in one extension (e.g. book and pdf).
GitHub: github.com/nrennie/workshops-for-ukraine-quarto-extensions
Slides: nrennie.github.io/workshops-for-ukraine-quarto-extensions
Blog: nrennie.rbind.io/blog/making-pretty-pdf-quarto
PrettyPDF extension: github.com/nrennie/PrettyPDF
Building extensions guide: quarto.org/docs/extensions/creating