Usage

Prerequisites

If you want to render the slides locally, you need to install the following tools:

• git
• R and RStudio Desktop
• Quarto CLI

Then, clone your new repository.

Tip

You can easily clone your new repository by following these steps in RStudio Desktop:

1. open RStudio Desktop
2. click on New Project
3. select Version control
4. select Git
5. paste the URL of your repository
6. check the name of the folder (same as the repository)
7. select the location on your drive in which your repository will be cloned

Repository metadata

Before starting writing your new presentation, you have to change the content of some files.

• CONTRIBUTING.md

  1. change the URL of the repository in several places
  2. change the email of the maintainer of the repository

• CODE_OF_CONDUCT.md

  1. change the email of the maintainer of the repository

• _quarto.yml

  1. change the title of the presentation in the tags title and pagetitle

• index.qmd

  1. change the URL of the repository in the tag footer
  2. change the path to your own .scss style in the tag style (if needed)

• sections/title-slide.qmd

  1. change the title of the presentation (inside ::: {.title} and :::)
  2. change the subtitle of the presentation (inside ::: {.subtitle} and :::)
  3. change first author name and social links (inside ::: {.column .author width="32%"} and :::)
  4. change first author affiliation (inside ::: {.column .affiliation width="32%"} and :::)
  5. add additional authors (up to two)

• images/logo-title-slide.png

  1. replace (but keep the same file name) this file to use your own image in the title slide

• images/logo-affiliation.png

  1. replace (but keep the same file name) this file to use your own image in the slide footer

• README.md

  1. remove the first chunk (link to this wiki)
  2. change the name of the GitHub account (rdatatoolbox) in several places
  3. change the name of the repository (quarto-template) in several places
  4. change the title, subtitle and image of the repository after <!-- Logo & Title -->
  5. edit the section Citation (after ## Citation)
  6. remove or edit the section Acknowledgments (after ## Acknowledgments)
  7. modify other sections as you want

• images/readme/logo-readme.png

  1. replace (but keep the same file name) this file to use your own image in the README

• images/wiki/

  1. delete this folder (only used for this Wiki)

Note

If you want to use a different license (default is CC BY 4.0), you have to:

1. change the content of the LICENSE.md file (visit the website choosealicense)
2. use a different license badge in the README.md
3. change the license name and icon in the tag footer of the index.qmd

Editing slide content

File organization

The Quarto template splits the presentation into sections (.qmd files stored in sections/). You can create as many sections as you like. You have to link a new section in the index.qmd as follow:

```{r}
#| child: "sections/new-section.qmd"
```

Alternatively, you can copy the content of all qmd files of the sections/ folder inside the index.qmd and delete the sections/ folder. But working with child documents makes easier the writing process, especially if you have a long presentation or want to reuse some slides.

Theme

If you want to modify the default theme, change the content of the styles/main.scss file. Alternatively, you can create your own theme in a different scss file stored in styles/ and add a link to this file in the index.qmd:

theme: [default, "styles/new-theme.scss"]

Quarto syntax

If you are not familiar with the Quarto and RMarkdown syntax, you can have a look at the Quarto Guide.

Rendering slides locally

To locally render the slides, open the index.qmd in RStudio and click on the button Render. This will create an index.html containing your presentation. Open the index.html in your favorite web browser to see your slides.

Caution

Do not render the child documents (.qmd files stored in sections/). You have to render only the index.qmd.

Updating online slides

Presentation files (index.html and index_files/) are listed in the .gitignore to keep the main branch clean. Your online presentation will be generated by a GitHub Action that will automatically convert the index.qmd into an index.html and push presentation files on the gh-pages branch. This action is triggered after a push on the main branch.

After a few minutes, your online presentation will be available at: https://__ghaccount__.github.io/__reponame__, where __ghaccount__ is your GitHub account (or GitHub organization) and __reponame__ your repository name.

Tip

You can disable the trigger of this action by adding [no ci] in your commit message. This can be interesting if you modify non Quarto files (e.g. README.md, CONTRIBUTING.md and CODE_OF_CONDUCT.md).

For instance: git commit -m "edit README [no ci]".