```{r, warning=TRUE, message=TRUE}
1:5
```
#> [1] 1 2 3 4 5
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.
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 / Quarto that is familiar to many R users.
The overall objective for this session is to:
More specific objectives are to:
index.html
file).format: docx
or format: html
, to create different file outputs._quarto.yml
file along with Quarto options to apply the understanding of how websites work and to build then them.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:
edit_file("index.qmd")
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/learning.qmd
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/learning.qmd
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, by adding format: html
to each YAML header. But we’d be duplicating a lot of options and it would be annoying to change all of them if you wanted something different. Instead, we can put it in the _quarto.yml
file and set the format:
for all files in the project. Like the website:
and project:
settings, format:
is a “top-level” option (meaning it doesn’t go under any other option in the file). There are many many options in format:
we can set, 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
Since we now have set the output format to HTML in the _quarto.yml
file, let’s remove the same setting from the doc/learning.qmd
file, so that both format:
and (if it exists) execute:
is removed.
While we have enough for Quarto to know how to build the website, let’s add one more thing to the Quarto settings. 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
When building a website, Quarto will render all .md
, .Rmd
, and .qmd
files in the project. To stop Quarto from rendering certain files, you can either prefix the file with _
(e.g. _learning.qmd
) or you can use the render:
setting and use !
before the file name you want to not render, which looks like this in the _quarto.yml
file:
project:
type: website
render:
- "!doc/learning.qmd"
Now let’s build the website. You can either use the “Render” button on the top or use 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.
The next step is to commit the changes we’ve made, but you’ll also see that a new folder called _site/
has been created. This folder contains all the files that form the website, like the HTML files and style files. While we could add these files to the Git history and make it so that GitHub uses those to host as a website, we’re going to set up GitHub later to build the website for us automatically. So we’ll add the _site/
folder to the .gitignore
file with:
use_git_ignore("_site")
Now we can commit the changes to the _quarto.yml
, the .gitignore
file, and the index.qmd
file to the Git history with or with the Palette (, then type “commit”).
_quarto.yml
file and update targetsTime: ~5 minutes.
Like we did in Chapter 5 with the editor
setting we added in our Quarto file, let’s make this setting global to the whole project. Cut and paste that metadata from doc/learning.qmd
into the bottom of _quarto.yml
:
editor:
markdown:
wrap: 72
canonical: true
Next, update the _targets.R
file by changing:
name
argument to quarto_website
, since we’re building a site now not just docs, and,path
argument to point to the main project folder "."
(.
means “the same folder _targets.R
is in)It should look like this now:
tar_quarto(
name = quarto_website,
path = "."
)
Then, finish up by:
targets::tar_make()
with the Palette (, then type “targets run”) to rebuild everything and test that the pipeline works.There is a way that we could create the website and save it in 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 would need to 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, including rendering all the R code.
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 , 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 .qmd
file. Commit this folder to the Git history with or with the Palette (, then type “commit”).
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 () along with typing the text “terminal”.
quarto publish gh-pages
Or, we can make use of the R’s system()
function by typing in the R Console:
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
permissions:
contents: write
pages: write
jobs:
build-deploy:
runs-on: ubuntu-latest
steps:
- name: Check out repository
uses: actions/checkout@v4
- 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
# From https://github.com/r-lib/actions/tree/v2-branch/setup-r
- 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 with or with the Palette (, then type “commit”) and push the changes up to GitHub. While we wait for the GitHub Action to finish, complete the next exercise.
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 the website:
section, and adding this to the bottom of it, so it should look like this:
website:
title: "Lipidomics analysis"
navbar:
left:
- href: index.qmd
text: "Home"
- href: doc/learning.qmd
text: "Report"
page-footer:
center:
- text: "License: CC BY 4.0"
Check that it works by rendering the website locally again with . Scroll to the bottom of the webpage that pops up to check that it has been added.
If it shows up, commit the changes to the Git history with or with the Palette (, then type “commit”) and then push up to GitHub. Wait for the GitHub Action to complete and you can now check that your website online also has the changes.
Next, let’s add some discoverability items to the README.md
file and to the GitHub repository.
Go to your project’s GitHub repository. A quick way of doing that is using browse_project()
from usethis.
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”.
On your project’s GitHub repository 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. with edit_file("README.md")
). Add some text below the first #
header, pasting the link where the LINK
text is in this template:
Check out the project's [website](LINK).
Commit the changes to the README.md
to the Git history with or with the Palette (, then type “commit”).
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.
index.qmd
file as well as the _quarto.yml
file with Quarto settings to build a website.use_ccby_license()
) to allow others to re-use your work.