Cookiecutter Quarto Website

A Cookiecutter template to make a project that is a Quarto website with places for slides, notebooks, and images.

• GitHub repo: https://github.com/eldobbins/cookiecutter-quarto-website
• Documentation: https://cookiecutter-pypackage.readthedocs.io/
• Free software: BSD license

Features

• Contains the basic building blocks to create a Quarto based website or a Quarto web book.
  • _quarto.yml configuration file to generate the website navigation or a book table of contents.
  • index.qmd to serve as the homepage of the website or the first chapter of the web book.
  • about.qmd to provide a citation for the website or an appendix in the web book.
  • optionally included R code block as an example on inline code.
• a GitHub action workflow to publish the website to GitHub Pages
• .gitignore file that will ignore the rendered HTML of the site
• several subdirectories to install content into
• a conda environment to allow quarto to run. Includes JupyterLab for the notebooks.

How to Create a New Project

Here are the commands to set-up a new project and to conntect it to a GitHub repo with automatic publishing via GitHub Actions.

1. Install Cookiecutter on your local computer using the Cookiecutter Installation Instructions. I prefer the conda option and an environment called cookies generated from the included environment.yml file.

   1. conda env create --file environment.yml
   2. conda activate cookies

2. Start a new GitHub repo using the online developer platform (hereafter called github.com). Go to your equivalent of https://github.com/eldobbins?tab=repositories and click the New button.

   1. Note the repository name you choose (i.e. new-quarto-website)
   2. Create a README.md file (and a main branch) while making the repo

3. Still at github.com, create the new branch in GitHub that will contain the rendered HTML website. That branch should be called gh-pages.

4. Still at github.com, to ensure GitHub Pages are enabled, navigate to Settings > Pages and make sure "Build and Deploy" uses the gh-pages branch.

5. To ensure the publishing Action has permission to write to gh-pages, navigate to Settings > Actions > General > Workflow Permissions and then check the “Read and Write Permissions” box.

6. To add a link to the new webpages in the repo, go to the Code tab and click the gear in the About section to the right. For Website, check the box for Use your GitHub Pages website. If you click that link now, you will see the contents of the README.md file - so basically nothing yet.

7. On the command line of your local machine, use your chosen method to generate a new project from the template. For instance: cookiecutter gh:eldobbins/cookiecutter-quarto-website.

   1. The name of the directory will be generated from your responses to the interactive prompts. For our example, enter "New Quarto Website" to match the repository name above.

8. Make the new directory a git repo, and set the remote to your GitHub account

   cd new-quarto-website
   git init
   git branch -M main
   git add -A
   git commit -m "Make new repo from cookiecutter-quarto-website"
   git remote add origin [email protected]:eldobbins/new-quarto-website
   git remote -v
   git push --force -u origin main

9. Check the Actions tab at github.com. You should see a queued or successful event called pages build and deployment. Wait till it finished. (Refresh the page to update its progress.)

10. Look at the new website. If you see the README text, then the page did not build or deploy. Check the Actions tab for error messages and fix them.

11. If using a web-book, it can be rendered into PDF format on the command line of your local computer with quarto render --to pdf. You might have to enable SVG support. Quarto's PDF Format Improvements includes install instructions, but librsvg, available via Conda and conda-forge, also works.

More Sources of Information

Here are some places to look for information if you get stuck.

Follow Quarto's instructions to authorize GitHub Actions for your repo if they aren't enabled by default. There are some screenshots that might help.

Follow Openscapes's instructions for Set-up GitHub Publishing. You can skip the section on GitHub Actions because this should already be done. But you will need to make a new gh-pages branch and use it for the published website.

A very detailed workflow for how to use a Cookiecutter template to make a GitHub repo can be found at https://gist.github.com/cjtu/74a38e1ad066e714218762b910d0910e

To find other Cookiecutter templates, try https://github.com/search?q=cookiecutter&type=Repositories