edit_file("index.qmd")
If you find any typos, errors, or places where the text may be improved, please let us know by providing feedback either in the feedback survey (given during class) or by using GitHub.
On GitHub open an issue or submit a pull request by clicking the " Edit this page" link at the side of this page.
9 Publicizing your analyses with a website
đ§ This section is being actively worked on. đ§
Disseminating our research and work is one of the key tasks of being a researcher. We researchers are sadly very limited in our focus on publishing papers, when our work can encompass much more than just papers and when there are other forms of publishing aside from papers. One of the most effective forms of disseminating content is in creating a website, thanks to the power of Google indexing.
With current software tools and services, Making simple websites like blogs has historically been fairly easy. Making websites presenting analytical work and outputs on the other hand, has been a difficult area. Over the last 10 years, many tools and packages have been created that try to simplify that task. They each have had their strengths, and their major flaws. The most recent software, though, is a massive improvement of previous attempts. In this session we will be covering how to make websites for code-based analysis projects that builds on top of R Markdown that is familiar to many R users.
9.1 Learning objectives
The overall objective for this session is to:
- Explain what a website is, what minimum files are needed, and how to use Quarto as a framework for creating them and including them as part of a pipeline.
More specific objectives are to:
- Describe how websites are essentially folders and files, where some files need to be named a specific way (like the
index.html
file). - Explain how Quarto executes R code in a document and creates different file formats from it, like Word or HTML. Use Quartoâs YAML header options, like
format: docx
orformat: html
, to create different file outputs. - Use the
_quarto.yml
file along with Quarto options to apply the understanding of how websites work and to build then them. - Use GitHub Actions to automate generating and uploading the website, then demonstrate how to make the material open by adding a license to the repository.
- Continue applying the concepts and functions used from the previous sessions.
9.2 Exercise: What is a website?
Time: ~5 minutes.
With your neighbour, discuss and come to an agreement about what exactly is a website? Could you explain it to an 80 year old? Or a 10 year old? Or to the class? Donât look ahead! đ
Ask if anyone wants to share, though they donât need to if they donât feel comfortable with it.
9.3 Websites, what they are and why researchers should create more
Talk through this point, showing the websites and reinforcing that a website isnât anything special, itâs just a different type of file then they typically use or create.
Websites are a bit of a mystery in many ways. You open a browser, go to Google, search for something, click a link, scroll through the website, and read text, view images, or watch videos. But what are websites actually?
At their simplest and most basic core, a file on your computer and a webpage you click into are exactly the same. A website is literally a series of folders and files on a server in another country. Letâs use Posit (the new RStudio company name) as an example. The website https://posit.co/ is like a folder called posit.co/
on your computer. The website https://posit.co/resources/ (notice the resources/
ending) is like a resources/
folder in the posit.co/
main folder on your computer. But you might ask, you just said a webpage is like a file, so where is the file name in https://posit.co/resources/? Well, browsers do something special when they see an URL with no file ending: They assume some default files to look for. When a URL doesnât include a file ending, the browser looks for files that are named either index
or default
. The most common file name for a webpage is index.html
. But it can also be index.php
, index.asp
, or default.htm
. We can test which file name a webpage is by typing the file name at the end of the URL. If we try https://posit.co/resources/index.html, we get a 404 error, meaning the file doesnât exist. But if we try https://posit.co/resources/index.php, if works! So making a website is as simple as having HTML files in a folder and uploading that folder onto a website hosting service. The services themselves can be tricky to use, but some are dead easy, like GitHub Pages is, which we will show later on.
So why should researchers make websites? Because it is the easiest way to disseminate your work, your projects, who you are as a researcher, and to have more impact and outreach. Given the current tools available and their ease of use, there is no reason any researcher (even non-technical ones) couldnât use websites as a way of publishing more of your work. Especially since if you are already learning about the workflow around using R, building functions, writing R Markdown (or Quarto), and using Git and GitHub, adding a website builder into this workflow is surprisingly easy.
9.4 What is Quarto and why use it?
Quarto is the next-generation R Markdown document generator. You might not even realize it, but if you are using a relatively recent version of RStudio, you are already using Quarto to knit your R Markdown documents. In terms of writing Markdown syntax, there is no difference between R Markdown and Quarto (since they both use Pandoc internally). The differences become obvious when you want to make more complex outputs like websites, books, or presentations or if you want to use another language like Python.
Quarto is âlanguage-agnosticâ, meaning it isnât limited to only R (unlike R Markdown for the most part). And it is even easier to use than R Markdown and the documentation on Quartoâs website is very high quality. For instance, with the use of the âSearchâ feature in the Quarto website (in the right-hand corner), you can search the documentation very easily. Over the next few years, R Markdown will be slowly phased out in favour of Quarto, for good reason. It is an massive upgrade in features and usability.
Letâs start the comparison with the YAML header differences between R Markdown and Quarto:
Quarto: Word
format: docx
Quarto: HTML
format: html
R Markdown: Word
output: word_document
R Markdown: HTML
output: html_document
As you can see, they arenât too different. But as you use it more though, it becomes obvious how powerful Quarto is. Letâs open the doc/report.Rmd
file and delete all the existing YAML metadata and convert to the formal Quarto format. Weâll create a HTML output document for now.
title: "Analysis of lipidomics"
format: html
We can use the same keybinding shortcut as with R Markdown: Ctrl-Shift-K
. You can also use the Command Palette (Ctrl-Shift-P
) followed by typing ârenderâ.
One big upgrade from R Markdown is that Quarto has a strong focus on scholarly writing and formatting, for instance by adding authors and affiliation metadata that gets added to the output document. It looks like:
author:
- name: Jane
orcid: 0000-0000-0000-0000
email: mymail@email.com
affiliations:
- name: Insitution Name
address: Street 10
city: City
postal-code: 0000
9.5 Exercise: Convert R Markdown YAML to Quarto style
Time: ~10 minutes.
In the doc/report.Rmd
file, add your author information to the YAML header.
- Add the
author:
metadata below thetitle:
and above theformat:
metadata. - Include your
name
andaffiliations
(with only the- name:
for institution). - Render the document with
Ctrl-Shift-K
. See what gets changed. - Replace
format: html
withformat: docx
and re-render the document. Switch back tohtml
. - Commit the changes to the Git history.
9.6 Using Quarto to build a project website
Now for the fun part, to use Quarto to build a website! At this stage, we only need two files: An index.qmd
file and a _quarto.yml
file. As we covered above, a browser will always look for a file called index
when the URL is only a folder. So for our main project folder, we need this file. Letâs create this file with {usethis}
to both create and than open it:
We wonât add much for now, only need to add a #
header:
# Lipidomics study
Next, letâs create the _quarto.yml
file that will have all the settings for the website.
edit_file("_quarto.yml")
There are many âtop-levelâ settings that we can include in this file. The first one is the project:
metadata, which tells Quarto details about the project as a whole. Since we want to create website, the option to set it would be type: website
:
project:
type: website
The next bit is to tell Quarto some details about the website. Websites in general are structured with the content, a navigation bar (ânavbarâ), and possibly some links on the side (think of how websites like YouTube or Twitter are structured). This is the same for Quarto. Each included .Rmd
, .md
, or .qmd
files are the content and Quarto adds the navbar. But we have to include what gets added to the navbar.
The first âtop-levelâ metadata is website:
and the first second-level metadata is usually the title:
of the website (that will be shown on the navbar). Next, letâs set up the navbar:
second-level header. There are two sub-levels to navbar:
, left:
and right:
. These tell Quarto what links should be put on the right-side of the navbar or the left-side. Weâll start with the left:
. Underneath, we need to give it a list of either file names or a pair of href:
and text:
or icon:
metadata. To keep things simple, weâll use the href:
and text:
for each item for the index.qmd
and the doc/report.Rmd
files. Like a list in Markdown, a list in YAML starts with a -
, where a pair of metadata belong to a single -
. Our website:
settings should look like this now:
website:
title: "Lipidomics analysis"
navbar:
left:
- href: index.qmd
text: Home
- href: doc/report.Rmd
text: "Report"
After weâve set the settings for the website:
, we need to tell Quarto what output files to create. We could do this for each individual file, but adding format: html
to each YAML header. But weâd be duplicating a lot of options. Instead, we can put it in the _quarto.yml
file and set the format:
for all files in the project. There are many many options we can set here, but the biggest one is what theme:
you want. There are several theme templates listed on the Quarto HTML Theming page. Weâll use a simple one called simplex
.
You can always override the project-level settings from the _quarto.yml
file by using the format:
(or other options) in the YAML header of an individual Markdown file.
format:
html:
theme: simplex
We have enough for Quarto to know how to build the website, but letâs add one more thing. For documents on an analysis, we usually want to show the output of code but not the code itself. In {knitr}
, there is a code chunk option echo
that hides the code from the final output document. In Quarto, you can set project-level {knitr}
options with the top-level metadata knitr:
along with the second-level metadata opts_chunk:
. Below it we can add settings that affect code chunks, like echo
. Letâs hide all code from the website:
knitr:
opts_chunk:
echo: false
We can almost build the website. The last thing to do is prevent the doc/lesson.qmd
file from being rendered (since we will use this file as more of a sandbox). To stop Quarto from rendering it when building the website, we simply need to add _
at the start of the filename. So letâs do that with {fs}
.
::file_move("doc/lesson.qmd", "doc/_lesson.qmd") fs
Now letâs build the website. You can either use the âRenderâ button on the top of use Ctrl-Shift-B
for âBuildâ. Letâs do it now. The website should pop up in either the Viewer Pane or as a new window. If not, we can debug whatâs going on. Letâs commit the changes to the _quarto.yml
and other .Rmd
or .qmd
files to the Git history.
9.7 Exercise: Look through the new website folder
Time: ~5 minutes.
In your main project folder, there should now be a folder called _site/
. Look through the folder. What files are now created? Open up the index.html
file in your browser while in RStudio by clicking the index.html
file and then selecting the âOpen in web browserâ.
Recall how we described what a website is. Can you see how these files and folders are simply HTML files that the browser shows as website? In the browser URL, change the index.html
ending link to doc/report.html
. See how it changes to the file based on how it is structured in the folder?
9.8 Exercise: Add Quarto to the pipeline
Time: ~5 minutes.
While {targets}
is useful for connecting pipeline targets and keeping track of dependencies between them, it isnât made to track full websites. This is for many good reasons that are very technical and not necessary to describe here. So while we canât build the website with {targets}
, we should still connect the Quarto doc/report.Rmd
file with the rest of the pipeline. We previously used tar_render()
, but we should now use tar_quarto()
.
- Open the
_targets.R
file, find thetar_render()
code, and replace it withtar_quarto()
. Leave everything else the same. - Run
targets::tar_visnetwork()
(Ctrl-Shift-P
, then type âtargets visualâ) and thentargets::tar_make()
(Ctrl-Shift-P
, then type âtargets runâ). - Commit only the changes made to
_targets.R
to the Git history.
Click for the solution. Only click if you are struggling or are out of time.
list(
# ...,
tar_quarto(
name = report_rmd,
path = "doc/report.Rmd"
) )
9.9 Exercise: Add collaboration setting to _quarto.yml
file
Time: ~5 minutes.
Like we did in Chapter 5 with the editor_options
setting we added in our R Markdown file, letâs make this setting global to the whole project. Cut and paste that metadata from doc/lesson.qmd
into the bottom of _quarto.yml
:
editor_options:
markdown:
wrap: 72
canonical: true
9.10 Automate rendering the website
There is a way that we could create the website into the _site/
folder, commit it to Git, and have GitHub host the website for us. But than weâd be saving a lot of files that could be updated quite often, which is annoying to keep track of. Instead, we can make use of GitHub Actions to build and publish our website for us.
There is a way to have GitHub completely (re-)build the website from scratch each time, including running any R code. However, our project doesnât have much R code and we have data that we donât keep in the project Git history. So we need to run the computations locally first so GitHub and build the website without the data. This is done through something called âexecution freezesâ. In the _quarto.yml
file, add this metadata settings to the bottom:
execute:
freeze: auto
Then when we re-render the website with Ctrl-Shift-B
, there will be a new folder created called _freeze/
. Inside this folder are instructions to Quarto on how to run the code chunks inside the .Rmd
file. Commit this folder to the Git history.
To get GitHub Actions to build the website we need to do two things first. Run a command to set things up and then add a new Action workflow file.
To set our repository up for the Action, we need to run quarto publish gh-pages
once in the Terminal (not the R Console). We open the Terminal either through the menu Tools -> Terminal -> New Terminal
or with the Command Palette (Ctrl-Shift-P
) along with typing the text âterminalâ. Or, we can make use of the Râs system()
function:
system("quarto publish gh-pages")
Next is add the Action workflow file:
edit_file(".github/workflows/build-website.yaml")
Then we can copy and paste the template code from the Quarto Example Action file, which is (slightly modified) below. We donât need to understand this code, at least not for this course. Because it is template code, itâs there to be copied and pasted (for the most part).
on:
push:
branches:
- main
- master
name: Render and Publish
jobs:
build-deploy:
runs-on: ubuntu-latest
steps:
- name: Check out repository
uses: actions/checkout@v3
- name: Set up Quarto
uses: quarto-dev/quarto-actions/setup@v2
with:
# To install LaTeX to build PDF book
tinytex: false
# uncomment below and fill to pin a version
# version: 0.9.600
- name: Publish to GitHub Pages (and render)
uses: quarto-dev/quarto-actions/publish@v2
with:
target: gh-pages
env:
# this secret is always available for github actions
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Letâs commit this new file to the Git history and push the changes up to GitHub. While we wait for the GitHub Action to finish, complete the next exercise.
9.11 Exercise: Add licensing information to repository
Time: ~10 minutes.
Youâve now created and published a website! If you value sharing though, thereâs a few extra things you need to do. Whenever you create something, legally it is copyrighted to you. If you do nothing else, no one is able to use what you share because legally they are not allowed to. Thatâs where licenses come in. A license is a legal document that tells others what they can and canât do with your copyrighted material. If you are publishing research work or other creative works and you want others to easily re-use it, you need to add a license document to your repository. A commonly used and recommended license for research and creative work is the Creative Commons Attribution 4.0 license, so we will use that.
In the R Console, type out
use_ccby_license()
.Add a simple license text to the bottom of each webpage by opening
_quarto.yml
, going to thewebsite:
section, and adding this to the bottom of it:page-footer: center: - text: "License: CC BY 4.0"
Check that it works by rendering the website again with
Ctrl-Shift-B
. Scroll to the bottom of the webpage that pops up to check that it has been added.
Next, letâs add some discoverability items to the README.md
file and to the GitHub repository.
Go to your projectâs GitHub page.
Confirm that the Actions worked by going to the âActionsâ tab. If there is a green check mark there, than continue to the next item. Otherwise, put up a âhelp stickyâ.
Open up your projectâs GitHub page and go to
Settings -> Pages
. You should see a link to your new website. Copy that link.Go to the âCodeâ tab, then click the gear icon on the right side, to the right of âAboutâ. In the box that pops up, paste the link in the âWebsiteâ textbox.
In your RStudio project, open up the
README.md
file (e.g. withedit_file("README.md")
). Add some text below the first#
header, pasting the link where theLINK
text is in this template:Check out the project's [website](LINK).
Commit the changes to the
README.md
to the Git history.
Sometimes you might make a change to files that arenât part of the website and donât want to trigger the GitHub Action, since it would be a waste of resources (computing time still costs energy). GitHub Actions run every time you push up. So if you donât want the last commit in the Git history to trigger the Actions, you can add the text [skip actions]
to the end of the commit message.
9.12 Using Quarto-style code options
Walk through this section with them. They will use this information in the next exercise.
Another difference with Quarto compared to R Markdown is how code chunk options are set. While you can continue using {knitr}
style code chunk options, itâs best to start switching to using the Quarto style. Compare them below.
knitr-style chunk options
```{r, echo=FALSE, warning=TRUE}
1:10
```
Quarto-style chunk options
```{r}
#| echo: false
#| warning: true
```
Why the change? They needed to develop an approach that worked with other languages as well, like Python. {knitr}
is an R-specific package, so they needed a more language agnostic way of setting chunk options. A full list of the code chunk options is found in the Cell Reference section of the website.
9.13 Exercise: Make figures prettier
Time: ~25 minutes
Looking through the Cell Reference documentation, complete these tasks.
Add a
fig-cap
option to each of the figures.For the distribution and variation plots, set the code chunk option
column
topage
to make it bigger.
Look through the {ggplot2}
documentation on theme_set()
and theme()
to update the look of all your figures. In the setup
code chunk of the doc/report.Rmd
file, make a new theme object and use theme_set()
to apply that theme to all plots. Use this as a scaffold:
```{r setup}
# ... previous code
<- theme(
updated_theme # ... make changes
)
# Or start with a template like theme_classic()
<- theme_TEMPLATE() +
updated_theme theme(
# ...
)
theme_set(updated_theme)
```
9.14 Summary
- Use Quarto, along with their referring to their documentation, to create various types of output documents, including websites.
- Add an
index.qmd
file as well as the_quarto.yml
file with Quarto settings to build a website. - Make use of execution freezes and GitHub Actions to host your website on GitHub.
- Add a license file (for instance, with
use_ccby_license()
) to allow others to re-use your work. - Use Quarto code chunk options, along with
{ggplot2}
theme functions, to make figures more visually appealing on their own and in the document.