Quarto Websites

Full documentation available on the quarto website. There are many ways to achieve this, we will here present the quarto publish to gh-pages option, which I found to be easiest.

Rstudio git setup guide

1 Website creation steps

    1. Create a new R. project, in a new folder and chose the quarto website

    1. Build the website
    • Edit index.qmd : main home page
    • Edit _quarto.yml : for general website appearance (including navigation and side bars)
    • Write each page as a .qmd file,
    • Structure the website through the _quarto.yml
    • Preview the website by rendering the index.qmd file
    • Make sure all the .qmd files can be rendered without any error

2 Setting up the publication

For the initial publication of the website, a few setup steps are necessary, which will then facilitate the later publication updates.

  • Add the following lines to the .gitignore
.gitignore
/.quarto/
/_site/

If those files have already been committed before, refer to the procedure described in the git ignore guide

  • Commit and push your current progress.

  • In the terminal, enter the following git commands

Terminal
git checkout --orphan gh-pages
git reset --hard # make sure all changes are committed before running this!
git commit --allow-empty -m "Initialising gh-pages branch"
git push origin gh-pages

  • Double check that the source branch for publication on the github website has been indeed configured to “gh-pages”

  • Go back to your main branch, you will never have to touch the gh-pages branch ever again

3 Publishing

To publish or update your website enter the following command in the terminal

Terminal
quarto publish gh-pages

You will be prompted to confirm the update by a message similar to this one :

? Update site at https://OFCE.github.io/ermeeth_project/? (Y/n) ›

Enter Y to confirm or N to abort, press the Return key to act.

Done!

Astuce

  • Quarto will render all the .qmd files present in the repository, so make sure only the necessary ones are included in your website development branch.

  • In theory, you can build a website on an existing repository:

    • Create a clean branch (empty)
    • Structure it like a quarto website project (ie generate a temporary new quarto website project to obtain the necessary files) and run the process described at Section 2

  • Only one website per repository