This template can be used to publish a RevealJS website that has been written in Quarto. It includes a GitHub Action which will convert the Quarto source to HTML and publish them via GitHub Pages.
Its a useful way of making slides portable as they are then available via the URL and naturally the slides are version controlled.
Start by clicking on the "Use this Template" button and selecting "Create a new repository". You will have to choose a name for the repository and this should reflect the nature of your talk. When ready click on "Create repository from template" and this will copy all the resources into a new repository under your GitHub account ready for you to start using.
You MUST make sure your repository action settings are configured to allow read and write permissions.
You can find this settings at https://github.com/[USER]/[repo]/settings/actions.
Typically you will work on files on your local computer, staging and committing changes and periodically pushing to GitHub for backup and publishing. How you clone depends on what client you use but at the command line you can use...
git clone https://github.com/<USERNAME>/<REPOSITORY>Substitute <USERNAME> and <REPOSITORY> appropriately.
How you should edit _quarto.yaml and change the site-url to reflect your GitHub user account and the name of the
repository you have chosen for this project. Its probably wise to modify the title and description too. The sample
code below shows in capitals the fields you should modify.
project:
type: website
website:
title: "<INSERT_TITLE>"
site-url: https://<YOUR_GITHUB_USERNAME>.github.io/<NAME_OF_REPOSITORY>
description: "<INSERT_DESCRIPTION>"This template uses some extensions (quarto-clean, QR extension, confetti), openlinksinnewpage and reveal-header these need to be installed locally before you can proceed.
quarto add --no-prompt jmbuhr/quarto-qrcode
quarto add --no-prompt grantmcdermott/quarto-revealjs-clean
quarto add --no-prompt ArthurData/quarto-confetti
quarto add --no-prompt davidwilby/openlinksinnewpage
quarto add --no-prompt shafayetShafee/reveal-headerYou will need to run quarto publish gh-pages once locally before deploying this template. This creates a new branch
gh-pages which is where the resulting pages are published to and pushes them to GitHub.
quarto publish gh-pagesYou are now ready to create your slides by editing the index.qmd in the root of the repository. For more information
on writing RevealJS slides in Quarto see the RevealJS guide and the
Revealjs Reference.
When you stage, commit and push your commits to GitHub the quarto-publish.yaml will run.
A pre-commit configuration is included (see .pre-commit-config.yaml) and includes a hook for
markdownlint-cli2 (see .markdownlint-cli2.yaml for
configuration). To use pre-commit you will have to install pre-commit install in your cloned repository. This requires
pre-commit to be installed on your system or within a Python Virtual Environment. To find out more about installing
and configuring pre-commit see the article pre-commit : Protecting your future
self or refer to the official documentation.
There are a growing number of useful Quarto extensions. Five are included in this
template and they are also installed during the publishing and deployment of the resulting slides as they are listed in
the quarto-publish.yml under the Install Quarto Extensions step. You should have installed these locally as
instructed above.
If you use additional extensions then as well as installing them locally on your computer you MUST remember to add
them to the Install Quarto Extensions section of .github/workflows/quarto-publish.yaml otherwise your pages will not
build and deploy.
The quarto-qrcode extension is particularly useful as it simplifies generating and embedding QR Codes that link to websites in your slides.
The quarto-revealjs-clean theme is a nice (clean!) theme. For a full example of all the features of this theme see the authors quarto-revealjs-clean-demo.
The confetti extension adds some eye-candy and throws confetti over
your slides whenever you press the c button. They originate from the mouse location and therefore follow it around.
The openlinksinnewpage extension does what it says on the tin and
ensures that when you click on a link in the resulting slides it will open a new tab/page (this saves you and others who
may not know of the shortcut from having to hold down Ctrl to achieve the same effect).
The reveal-header extension allows you to add headers as well as
footers to all slides. This template includes a simple text header: nested under the format: <theme>: YAML header
in index.qmd. Please refer to the documetation for further
customisation such as adding a header-logo and other options available with this extension.
The beauty of Quarto is that it is a literate programming system which means you can embed code that is executed and the results, whether that is tables, figures, or numbers, can be included in the resulting document. Quarto supports several languages including perhaps the two of the most popular languages R and Python.
You will likely have R installed locally along with all the packages that are required (and perhaps even use reproducible environments using renv or pak).
For slides to build and execute your R code correctly you need to enable installation of R and the required packages in
the .github/workflows/quarto-publish.yaml. A sample section is already present that should just need un-commenting,
but may need tweaking if you use any packages to manage a reproducible environment.
Similarly with Python you likely have Virtual Environments configured locally to run your Python code, and these should
have be detailed in a requirements.txt file so they can be installed when the GitHub Workflow is executed to build
your pages on GitHub.
You will need to enable installation of Python and these packages in the .github/workflows/quarto-publish.yaml and
a sample section is already present that can be un-commented if required.