Websites and blogs

SciPy 2024: Unlocking Dynamic Reproducible Documents
A Quarto Tutorial for Scientific Communication

Mine Çetinkaya Rundel

Duke University + Posit PBC

Anatomy of a Quarto project

Quarto projects

  • Quarto projects have a _quarto.yml file

  • The type field in this file indicates the type of project:

    • default: Collection of documents

    • website: Websites (and blogs)

    • books: Books

    • manuscript: Journal manuscript with embedded computing and JATS bundle

Components

A Quarto Project is a directory that contains a file called _quarto.yml.


This is a Quarto Project.

my-folder/
├── _quarto.yml
├── my-document.ipynb

This is not.

my-folder/
├── my-document.ipynb

_quarto.yml

A YAML file with particular keys and values that Quarto recognizes. Unrecognized keys are ignored.

_quarto.yml
project:
  title: "A Barebones Project"

_quarto.yml

A YAML file with particular keys and values that Quarto recognizes. Unrecognized keys are ignored.

_quarto.yml
project:
  type: website
  output-dir: docs

website:
  page-navigation: true
  title: "Unlocking Dynamic Reproducible Documents"
  description: "A Quarto Tutorial for Scientific Communication on Quarto at SciPy 2024"

  repo-url: https://github.com/mine-cetinkaya-rundel/quarto-scipy24
  repo-actions: [edit, issue]

  open-graph: true

  sidebar:
    background: "#D1D9E3"
    logo: "images/quarto-scipy24-site-logo.png"
    pinned: true
    align: center
    tools:
      - icon: github
        href: https://github.com/mine-cetinkaya-rundel/quarto-scipy24
        text: GitHub repo
      - icon: code-square
        href: https://code.visualstudio.com/
        text: VS Code

    style: docked
    search: true
    collapse-level: 2
    contents:
      - href: index.qmd
        text: Home
      - href: setup.qmd
        text: Setup
      - section: Part 1
        contents:
          - href: 1-1-hello/index.qmd
            text: Hello
          - href: 1-2-documents/index.qmd
            text: Documents
          - href: 1-3-presentations/index.qmd
            text: Presentations
          - href: 1-4-dashboards/index.qmd
            text: Dashboards
      - section: Part 2
        contents:
          - href: 2-1-websites/index.qmd
            text: Websites and blogs
          - href: 2-2-books/index.qmd
            text: Books
          - href: 2-3-manuscripts/index.qmd
            text: Manuscripts

  page-footer:
    right: "This page is built with 💚 and [Quarto](https://quarto.org/)."
    left: "© Copyright 2024, Mine Çetinkaya-Rundel"
    background: "#D1D9E3" # Arylide Yellow

format:
  html:
    theme:
      light: [cosmo, style/quarto-scipy24.scss]
      dark: [cosmo, style/quarto-scipy24.scss, style/dark.scss]
    linkcolor: "#58779b"
    toc: true
    code-copy: true
    code-overflow: wrap
    mainfont: "Atkinson Hyperlegible"

execute:
  freeze: auto
  echo: true

Quarto websites

  • Websites are essentially format: html + a Quarto Project file

  • But a website is different than format: html in that it has multiple pages

  • Websites and books are very similar in that they associate multiple pages/resources into a connected resource

    • In books, you can cross-reference between pages (chapters), but (currently), you can’t cross-reference between pages in websites

Our turn

Let’s build a website that features a few of the notebooks we worked on and highlight the following features of Quarto websites:

  • Add a _quarto.yml
  • Create a landing page: index.qmd
  • Explore navigation options: navbar, sidebar
  • Apply themes, including a light and dark theme toggle
  • Publish to QuartoPub with quarto publish
  • An aspect of the workshop webpage that you fancy?

Your turn

  • Add one more notebook that has at least one executable code cell and add it to the navigation list in _quarto.yml and render your site.
  • Add an about page, about.qmd, personalize it, and add it to the navigation list in _quarto.yml and render your site.
  • Re-publish on QuartoPub with quarto publish.
10:00

Listings

Listings

  • Listings enable you to automatically generate the contents of a page (or region of a page) from a list of Quarto documents or other custom data

  • Useful for creating blogs, providing navigation for large numbers of documents, or any other scenario where you’d like the contents of a page to be automatically updated as documents are added, updated, and removed

Blogs

Let’s now add a blog component to our website:

  • Move two of your notebook files into a new a folder called posts.
  • Collect these notebooks in a new blog page using the listings feature.
    • Don’t forget to make corresponding changes in your _quarto.yml file.
  • Experiment with the style of listings and choose one you like.

Computations

When should code be re-run?

  • You might have a reason to re-run all code in a Quarto website (every single cell in every single document) every time you render the website.

  • But, chances are, that’s not what you want.

    • Just playing around styling – you probably don’t want to run the code again

    • Changed some code in a document – you probably want to re-run the code in that document, but not necessarily others

    • Made a big change affecting computations on many or all pages – you probably want to re-run all code

  • freeze and cache options give you fine control over these decisions

Freeze

  • The freeze option controls when/if computational documents be re-rendered during a global project render:
execute:
  freeze: true  # never re-render during project render
execute:
  freeze: auto  # re-render only when source changes
execute:
  freeze: false  # always re-render

  • The freeze option is typically added to a _metadata.yml file within a specific directory, affecting all files in that directory.

  • For blogs, set feeze in _metadata.yml at the root of the posts directory.

  • You can have it only within specific subdirectories for more complex sites.

Freeze and Jupyter notebooks

  • When rendering an .ipynb, Quarto will not execute the cells within the notebook by default, assuming that you have already executed them while editing the notebook

  • To execute the cells, pass the --execute flag to render:

Terminal
quarto render notebook.ipynb --execute
  • Or specify this behavior within the notebook’s YAML front matter:
---
execute:
  enabled: true
---

Cache

  • Cache stores the results of computations for a specific file

  • Cache invalidation is triggered by changes in chunk source code (or other cache attributes you’ve defined)

  • cache can also be set at the chunk level, particularly useful for computationally expensive chunks

Freeze vs. cache

  • Freeze option is typically set

    • for the whole website in _quarto.yml, or

    • for files within a directory in _metadata.yml in that directory

execute: 
  freeze: auto
  • Cache option is typically set for a given file or for individual chunk(s) in a file.
execute:
  cache: true

or

```{python}
1 + 1
```
2

Publishing

QuartoPub

  • Quarto Pub is a free publishing service for content created with Quarto. It is ideal for blogs, course or project websites, books, presentations, and personal hobby sites.

  • Publish with quarto publish:

Terminal
quarto publish quarto-pub
  • Gain a _publish.yml that is safe to check into version control.

Other venues

Wrap up

Learn more

quarto.org/docs/websites

Questions

Any questions / anything you’d like to review before we wrap up this module?

🔗 bit.ly/quarto-scipy24