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 and confetti) and these need to be installed locally before you can proceed.

quarto install --no-prompt extension jmbuhr/quarto-qrcode
quarto install --no-prompt extension grantmcdermott/quarto-revealjs-clean
quarto install --no-prompt extension ArthurData/quarto-confetti

You 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-pages

You 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. Three 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. 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 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.