04:00
From Jupyter Notebooks to websites with Quarto
Mine Çetinkaya Rundel
Duke University + Posit
Pre-workshop
Setup
1. Tools: Have JupyterLab and/or VS Code (with Jupyter and Quarto extensions) ready to go
2. Software: Download and install Python and the pre-release version of Quarto:
- Python 3: https://www.python.org/downloads/
- Quarto 1.4.464: https://quarto.org/docs/download/prerelease.html
3. Packages: Install the following packages:
4. Exercises: Go to bit.ly/quarto-pydata-website, click on “Use this template” then “Create a new repository”. Once your repository is created, clone it locally and navigate to the repo folder.
Welcome
Code of Conduct
PyData has an engaged and respectful community made up of people from all over the world. We are committed to creating a productive, professional, and inclusive environment for everyone. All community members are expected to show respect and courtesy to other attendees throughout the conference, all conference events and online forums. Our code of conduct is strictly enforced.
Do not insult or put down others. Behave professionally. Remember that harassment and sexist, racist, or exclusionary jokes are not appropriate for PyData NYC.
All communication should be appropriate for a professional audience including people of many different backgrounds. Sexual language and imagery is not appropriate.
PyData NYC is dedicated to providing a harassment-free community for everyone, regardless of gender, sexual orientation, gender identity and expression, disability, physical appearance, body size, race, or religion. We do not tolerate harassment of community members in any form.
Thank you for helping make this a welcoming, friendly community for all.
About me
Professor of the Practice
Department of Statistical Science
Duke UniversityDeveloper Educator, Posit
- Teaching data analysis in computational notebooks for 10+ years
- Teaching and using Quarto for 2+ years
About you
Please share
- Name
- Professional affiliation
- What do you use computational notebooks for?
- What do you hope to get out of this tutorial?
Meeting you where you are
These materials are pitched at someone who:
knows some Python + Markdown
has worked in Jupyter Lab and/or VS Code
wants to learn about Quarto
I’ll teach you
More Markdown
New Quarto formats
New Quarto projects
Workshop structure
My turn
- Lecture segments
- Feel free to just watch, take notes, browse docs, or tinker around with the code
Our turn
- Lecture segments + live coding
- Follow along with live coding
Your turn
- Practice exercises for you
- Work on your own or with the person next to you
Getting help
During my turn and your turn segments – raise your hand
During our turn segments – also feel free to raise your hand for questions but if your question seems specific to your setup, I might come around and help during the next your turn break
Setup
1. Tools: Have JupyterLab and/or VS Code (with Jupyter and Quarto extensions) ready to go
2. Software: Download and install Python and the pre-release version of Quarto:
- Python 3: https://www.python.org/downloads/
- Quarto 1.4.464: https://quarto.org/docs/download/prerelease.html
3. Packages: Install the following packages:
4. Exercises: Go to bit.ly/quarto-pydata-website, click on “Use this template” then “Create a new repository”. Once your repository is created, clone it locally and navigate to the repo folder.
Let’s get started!
What is Quarto?
Quarto …
is an innovative, open-source scientific and technical publishing system compatible with Jupyter Notebooks and other popular mediums.
Artwork from “Hello, Quarto” keynote by Julia Lowndes and Mine Çetinkaya-Rundel, presented at RStudio Conference 2022. Illustrated by Allison Horst.
With Quarto …
you can weave together narrative and code to produce elegantly formatted output as documents, web pages, blog posts, books and more, with…
- consistent implementation of attractive and handy features across outputs: tabsets, code-folding, syntax highlighting, etc.
- defaults that meet accessibility guidelines as well as features that enable good practices for producing accessible documents
- natively multi-lingual, supporting for multiple languages like Python, Julia, Observable, and more via the Jupyter engine for executable code chunks
A tour of Quarto
Sit back and enjoy!
- Running individual cells and
quarto rendering entire document - Customizing output format options:
code-fold,toc - Cross referencing figures and tables
- Code cells: labels, alt-text for figures, cross references for figures and tables
- Lightbox effect
How it Works
Revisit: What is Quarto?
Quarto is a command line interface (CLI) that renders plain text formats (.qmd, .rmd, .md) OR mixed formats (.ipynb/Jupyter notebook) into static PDF/Word/HTML reports, books, websites, presentations and more.
Usage: quarto
Version: 1.4.464
Description:
Quarto CLI
Options:
-h, --help - Show this help.
-V, --version - Show the version number for this program.
Commands:
render [input] [args...] - Render files or projects to various document types.
preview [file] [args...] - Render and preview a document or website project.
serve [input] - Serve a Shiny interactive document.
create [type] [commands...] - Create a Quarto project or extension
create-project [dir] - Create a project for rendering multiple documents
convert <input> - Convert documents to alternate representations.
pandoc [args...] - Run the version of Pandoc embedded within Quarto.
typst [args...] - Run the version of Typst embedded within Quarto.
run [script] [args...] - Run a TypeScript, R, Python, or Lua script.
add <extension> - Add an extension to this folder or project
install [target...] - Installs an extension or global dependency.
publish [provider] [path] - Publish a document or project to a provider.
check [target] - Verify correct functioning of Quarto installation.
help [command] - Show this help or the help of a sub-command.Under the hood
jupyterevaluates Python code and returns a.mdfile along with the evaluated code- Quarto applies Lua filters + CSS/LaTeX which is then evaluated alongside the
.mdfile by Pandoc and converted to a final output format
Under the hood
with a wider lens…
jupyterorknitrevaluates Python, Julia, R, or Observable code and returns a.mdfile along with the evaluated code- Quarto applies Lua filters + CSS/LaTeX which is then evaluated alongside the
.mdfile by Pandoc and converted to a final output format
Aside: Lua filters
- Here is an example of a Lua filter that converts strong emphasis to small caps, from https://pandoc.org/lua-filters.html:
- Lua filters written by R/Python/Julia developers should be interchangeable between formats - not language specific!
- We won’t go into the details of writing Lua filters in this workshop, and you don’t need to worry about learning about Lua filters unless you’re working on extending Quarto.
From the comfort of your own homeworkspace
Rendering
in JupyterLab
In the Terminal via quarto render:
Terminal
in VS Code
Option 1: In the Terminal via
quarto renderOption 2: Using the Quarto Extension and clicking on Preview
Quarto formats
One install, “Batteries included”
Quarto comes “batteries included” straight out of the box:
HTML reports and websites
PDF reports
MS Office (Word, Powerpoint)
Presentations (Powerpoint, Beamer,
revealjs)Books
Manuscripts
…
- Any language, exact same approach and syntax
Many Quarto formats
| Feature | Quarto |
|---|---|
| Basic Formats | html, pdf, docx |
| Beamer | beamer |
| PowerPoint | pptx |
| HTML Slides | revealjs |
| Advanced Layout | Quarto Article Layout |
| Cross References | Quarto Crossrefs |
| Websites & Blogs | Quarto Websites, Quarto Blogs |
| Books | Quarto Books |
| Interactivity | Quarto Interactive Documents |
| Journal Articles | Journal Articles |
| Dashboards | More on this on Friday’s keynote! |
Your turn
In JupyterLab or VS Code, open the hello-penquins.ipynb file. Render the document to HTML.
In the YAML: Add an
authorfield and add your name.Add a markdown cell and write some text.
Modify the figure to add units to the axis labels: grams for body weight and mm (milimeters) for flipper length. Make sure the changes are reflected in the HTML output.
Change the html theme to
sketchy. (See https://quarto.org/docs/output-formats/html-themes.html for documentation on HTML theming.)
10:00
A pause
Where does the name “Quarto” come from?
Documents to projects
Anatomy of a Quarto document
Three components:
Metadata: YAML
Text: Markdown
Code: Executed via
jupyterorknitr
Weave it all together, and you have beautiful, powerful, and useful outputs!
Anatomy of a Quarto project
A Quarto Project is a directory that contains a file called
_quarto.yml.
This is a Quarto Project.
my-folder/
├── _quarto.yml
├── my-document.ipynbThis 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
A YAML file with particular keys and values that Quarto recognizes. Unrecognized keys are ignored.
_quarto.yml
project:
type: website
output-dir: _site
resources:
- "/docs/download/_download.json"
- "/docs/download/_prerelease.json"
- "/_redirects"
website:
title: "Quarto"
image: "quarto-dark-bg.jpeg"
favicon: "favicon.png"
google-analytics: "G-FV9Z7SDZ0M"
open-graph: true
twitter-card: true
site-url: https://quarto.org
repo-url: https://github.com/quarto-dev/quarto-web
issue-url: https://github.com/quarto-dev/quarto-cli/issues/new/choose
repo-actions: [edit, issue]
page-navigation: true
bread-crumbs: true
search:
show-item-context: true
type: overlay
algolia:
index-name: prod_QUARTO
application-id: ZPJB5I1QN7
search-only-api-key: 41be6c1e0a7fea4a51b107810facf577
analytics-events: true
show-logo: true
page-footer:
left: |
Proudly supported by
[{fig-alt="Posit" width=65px}](https://posit.co)
center:
- text: "About"
href: about.qmd
- text: "FAQ"
href: docs/faq/index.qmd
- text: "License"
href: license.qmd
- text: "Trademark"
href: trademark.qmd
right:
- icon: twitter
href: https://twitter.com/quarto_pub
aria-label: Quarto Twitter
- icon: github
href: https://github.com/quarto-dev/quarto-cli
aria-label: Quarto GitHub
- icon: rss
href: https://quarto.org/docs/blog/index.xml
aria-label: Quarto Blog RSS
navbar:
background: light
logo: quarto.png
logo-alt: "Quarto logo."
title: false
collapse-below: lg
left:
- text: "Overview"
href: index.qmd
- text: "Get Started"
href: docs/get-started/index.qmd
- text: "Guide"
href: docs/guide/index.qmd
- text: Extensions
href: docs/extensions/index.qmd
- text: "Reference"
href: docs/reference/index.qmd
- text: "Gallery"
href: docs/gallery/index.qmd
- text: "Blog"
href: docs/blog/index.qmd
- text: "Help"
menu:
- text: "Report a Bug"
icon: "bug"
href: "https://github.com/quarto-dev/quarto-cli/issues"
- text: "Ask a Question"
icon: "chat-right-text"
href: "https://github.com/quarto-dev/quarto-cli/discussions"
- text: "FAQ"
icon: "question-circle"
href: docs/faq/index.qmd
tools:
- icon: twitter
href: https://twitter.com/quarto_pub
text: Quarto Twitter
- icon: github
href: https://github.com/quarto-dev/quarto-cli
text: Quarto GitHub
- icon: rss
href: https://quarto.org/docs/blog/index.xml
text: Quarto Blog RSS
sidebar:
- id: get-started
title: "Get Started"
style: "floating"
collapse-level: 2
align: left
contents:
- docs/get-started/index.qmd
- text: "Tutorial: Hello, Quarto"
href: docs/get-started/hello/
- text: "Tutorial: Computations"
href: docs/get-started/computations/
- text: "Tutorial: Authoring"
href: docs/get-started/authoring/
- id: guide
collapse-level: 1
contents:
- section: "Guide"
href: docs/guide/index.qmd
contents:
- section: "Authoring"
contents:
- docs/authoring/markdown-basics.qmd
- docs/authoring/figures.qmd
- docs/authoring/tables.qmd
- docs/authoring/diagrams.qmd
- docs/authoring/videos.qmd
- text: "Jupyter Notebooks"
href: docs/authoring/notebook-embed.qmd
- docs/authoring/callouts.qmd
- docs/authoring/code-annotation.qmd
- docs/authoring/article-layout.qmd
- section: "Scholarly Writing"
contents:
- docs/authoring/front-matter.qmd
- docs/authoring/title-blocks.qmd
- docs/authoring/footnotes-and-citations.qmd
- docs/authoring/cross-references.qmd
- docs/authoring/create-citeable-articles.qmd
- docs/authoring/appendices.qmd
- section: "Computations"
contents:
- docs/computations/python.qmd
- docs/computations/r.qmd
- docs/computations/julia.qmd
- docs/computations/ojs.qmd
- docs/computations/execution-options.qmd
- docs/computations/parameters.qmd
- section: "Tools"
contents:
- section: "JupyterLab"
contents:
- text: "JupyterLab Basics"
href: docs/tools/jupyter-lab.qmd
- text: "JupyterLab Extension"
href: docs/tools/jupyter-lab-extension.qmd
- section: "RStudio IDE"
contents:
- text: "RStudio Basics"
href: docs/tools/rstudio.qmd
- section: "Visual Editor"
href: docs/visual-editor/index.qmd
contents:
- text: Editor Basics
href: docs/visual-editor/index.qmd
- docs/visual-editor/technical.qmd
- docs/visual-editor/content.qmd
- docs/visual-editor/options.qmd
- docs/visual-editor/markdown.qmd
- section: "VS Code"
href: docs/tools/vscode.qmd
contents:
- text: "VS Code Basics"
href: docs/tools/vscode.qmd
- text: "Visual Editor"
href: docs/visual-editor/vscode/index.qmd
- text: "Notebook Editor"
href: docs/tools/vscode-notebook.qmd
- docs/tools/neovim.qmd
- docs/tools/text-editors.qmd
- section: "Documents"
contents:
- section: "HTML"
contents:
- docs/output-formats/html-basics.qmd
- docs/output-formats/html-code.qmd
- docs/output-formats/html-themes.qmd
- docs/output-formats/html-multi-format.qmd
- docs/output-formats/html-publishing.qmd
- section: "PDF"
contents:
- docs/output-formats/pdf-basics.qmd
- docs/output-formats/pdf-engine.qmd
- section: "MS Word"
contents:
- docs/output-formats/ms-word.qmd
- docs/output-formats/ms-word-templates.qmd
- section: "Markdown"
contents:
- docs/output-formats/gfm.qmd
- docs/output-formats/hugo.qmd
- docs/output-formats/docusaurus.qmd
- docs/output-formats/all-formats.qmd
- section: "Presentations"
contents:
- text: "Overview"
href: docs/presentations/index.qmd
- section: docs/presentations/revealjs/index.qmd
contents:
- text: "Reveal Basics"
href: docs/presentations/revealjs/index.qmd
- docs/presentations/revealjs/presenting.qmd
- docs/presentations/revealjs/advanced.qmd
- docs/presentations/revealjs/themes.qmd
- docs/presentations/powerpoint.qmd
- docs/presentations/beamer.qmd
- section: "Websites"
href: docs/websites/website-basics.qmd
contents:
- docs/websites/website-basics.qmd
- docs/websites/website-navigation.qmd
- docs/websites/website-blog.qmd
- docs/websites/website-search.qmd
- docs/websites/website-tools.qmd
- docs/websites/website-about.qmd
- section: "Listing Pages"
href: docs/websites/website-listings.qmd
contents:
- docs/websites/website-listings.qmd
- docs/websites/website-listings-custom.qmd
- section: "Books"
href: docs/books/book-basics.qmd
contents:
- docs/books/book-basics.qmd
- docs/books/book-structure.qmd
- docs/books/book-crossrefs.qmd
- text: "Customizing Output"
href: docs/books/book-output.qmd
- section: "Interactivity"
contents:
- text: "Overview"
href: docs/interactive/index.qmd
- section: docs/interactive/ojs/index.qmd
contents:
- text: "Introduction"
href: docs/interactive/ojs/index.qmd
- docs/interactive/ojs/libraries.qmd
- docs/interactive/ojs/data-sources.qmd
- docs/interactive/ojs/ojs-cells.qmd
- docs/interactive/ojs/shiny.qmd
- docs/interactive/ojs/code-reuse.qmd
- section: "Examples"
contents:
- docs/interactive/ojs/examples/penguins.qmd
- docs/interactive/ojs/examples/sunburst.qmd
- docs/interactive/ojs/examples/arquero.qmd
- docs/interactive/ojs/examples/population.qmd
- docs/interactive/ojs/examples/noaa-co2.qmd
- docs/interactive/ojs/examples/github.qmd
- docs/interactive/ojs/examples/layout.qmd
- section: "Shiny"
contents:
- text: "K-Means"
href: https://jjallaire.shinyapps.io/kmeans-shiny-ojs/
- text: "Binning"
href: https://jjallaire.shinyapps.io/binning-shiny-ojs/
- text: "Data Binding"
href: https://jjallaire.shinyapps.io/data-shiny-ojs/
- text: "Covid Map"
href: https://jjallaire.shinyapps.io/covid19-bicartogram/
- section: docs/interactive/shiny/index.qmd
contents:
- text: "Introduction"
href: docs/interactive/shiny/index.qmd
- docs/interactive/shiny/running.qmd
- docs/interactive/shiny/execution.qmd
- docs/interactive/shiny/resources.qmd
- section: "Examples"
contents:
- text: "Old Faithful"
href: https://jjallaire.shinyapps.io/shiny-old-faithful/
- text: "K-Means"
href: https://jjallaire.shinyapps.io/shiny-k-means/
- text: "Diamonds"
href: https://jjallaire.shinyapps.io/shiny-diamonds/
- section: "Widgets"
contents:
- docs/interactive/widgets/jupyter.qmd
- docs/interactive/widgets/htmlwidgets.qmd
- docs/interactive/layout.qmd
- section: "Publishing"
contents:
- docs/publishing/index.qmd
- docs/publishing/quarto-pub.qmd
- docs/publishing/github-pages.qmd
- docs/publishing/rstudio-connect.qmd
- docs/publishing/netlify.qmd
- docs/publishing/confluence.qmd
- docs/publishing/other.qmd
- text: "Publishing with CI"
href: docs/publishing/ci.qmd
- section: "Projects"
contents:
- docs/projects/quarto-projects.qmd
- docs/projects/code-execution.qmd
- docs/projects/profiles.qmd
- docs/projects/environment.qmd
- docs/projects/scripts.qmd
- docs/projects/virtual-environments.qmd
- section: "Advanced"
contents:
- docs/authoring/includes.qmd
- docs/authoring/variables.qmd
- docs/output-formats/page-layout.qmd
- docs/authoring/language.qmd
- docs/authoring/conditional.qmd
- docs/extensions/nbfilter.qmd
- id: extensions
title: "Extensions"
contents:
- "---"
- section: docs/extensions/index.qmd
contents:
- text: "Shortcodes & Filters"
href: docs/extensions/listing-filters.qmd
- text: "Journal Articles"
href: docs/extensions/listing-journals.qmd
- text: "Custom Formats"
href: docs/extensions/listing-formats.qmd
- text: "Revealjs Extensions"
href: docs/extensions/listing-revealjs.qmd
- docs/extensions/managing.qmd
- "---"
- section: docs/extensions/creating.qmd
contents:
- text: "Overview"
href: docs/extensions/creating.qmd
- docs/extensions/lua.qmd
- docs/extensions/lua-api.qmd
- text: "Distribution"
href: docs/extensions/distributing.qmd
- "---"
- text: "Shortcodes"
href: docs/extensions/shortcodes.qmd
- text: "Filters"
href: docs/extensions/filters.qmd
- section: "Journal Articles"
href: docs/journals/formats.qmd
contents:
- docs/journals/formats.qmd
- docs/journals/templates.qmd
- docs/journals/authors.qmd
- docs/extensions/formats.qmd
- docs/extensions/revealjs.qmd
- docs/extensions/project-types.qmd
- docs/extensions/starter-templates.qmd
- id: manuscripts
title: "Manuscripts"
style: "floating"
collapse-level: 2
align: left
contents:
- text: Manuscripts Overview
href: docs/manuscripts/index.qmd
- text: "Authoring Manuscripts"
contents:
- text: Jupyter Lab
href: docs/manuscripts/authoring/jupyterlab.qmd
- text: VS Code
href: docs/manuscripts/authoring/vscode.qmd
- text: RStudio
href: docs/manuscripts/authoring/rstudio.qmd
- text: "Publishing Manuscripts"
href: docs/manuscripts/publishing.qmd
- text: "Next Steps"
href: docs/manuscripts/next-steps.qmd
- text: "---"
- text: "Manuscript Components"
href: docs/manuscripts/components.qmd
- id: reference
title: "Reference"
collapse-level: 3
contents:
- section: "Reference"
href: docs/reference/index.qmd
contents:
- section: "Formats"
contents:
- text: "HTML"
href: docs/reference/formats/html.qmd
- text: "PDF"
href: docs/reference/formats/pdf.qmd
- text: "MS Word"
href: docs/reference/formats/docx.qmd
- text: "OpenOffice"
href: docs/reference/formats/odt.qmd
- text: "ePub"
href: docs/reference/formats/epub.qmd
- section: "Presentations"
contents:
- text: "Revealjs"
href: docs/reference/formats/presentations/revealjs.qmd
- text: "PowerPoint"
href: docs/reference/formats/presentations/pptx.qmd
- text: "Beamer"
href: docs/reference/formats/presentations/beamer.qmd
- section: "Markdown"
contents:
- text: "GitHub"
href: docs/reference/formats/markdown/gfm.qmd
- text: "CommonMark"
href: docs/reference/formats/markdown/commonmark.qmd
- text: "Markua"
href: docs/reference/formats/markdown/markua.qmd
- section: "Wikis"
contents:
- text: "MediaWiki"
href: docs/reference/formats/wiki/mediawiki.qmd
- text: "DokuWiki"
href: docs/reference/formats/wiki/dokuwiki.qmd
- text: "ZimWiki"
href: docs/reference/formats/wiki/zimwiki.qmd
- text: "Jira Wiki"
href: docs/reference/formats/wiki/jira.qmd
- text: "XWiki"
href: docs/reference/formats/wiki/xwiki.qmd
- section: "More Formats"
contents:
- text: "JATS"
href: docs/reference/formats/jats.qmd
- text: "Jupyter"
href: docs/reference/formats/ipynb.qmd
- text: "ConTeXt"
href: docs/reference/formats/context.qmd
- text: "RTF"
href: docs/reference/formats/rtf.qmd
- text: "reST"
href: docs/reference/formats/rst.qmd
- text: "AsciiDoc"
href: docs/reference/formats/asciidoc.qmd
- text: "Org-Mode"
href: docs/reference/formats/org.qmd
- text: "Muse"
href: docs/reference/formats/muse.qmd
- text: "GNU TexInfo"
href: docs/reference/formats/texinfo.qmd
- text: "Groff Man Page"
href: docs/reference/formats/man.qmd
- text: "Groff Manuscript"
href: docs/reference/formats/ms.qmd
- text: "Haddock markup"
href: docs/reference/formats/haddock.qmd
- text: "OPML"
href: docs/reference/formats/opml.qmd
- text: "Textile"
href: docs/reference/formats/textile.qmd
- text: "DocBook"
href: docs/reference/formats/docbook.qmd
- text: "InDesign"
href: docs/reference/formats/icml.qmd
- text: "TEI Simple"
href: docs/reference/formats/tei.qmd
- text: "FictionBook"
href: docs/reference/formats/fb2.qmd
- section: "Code Cells"
href: docs/reference/cells/index.qmd
contents:
- text: "Jupyter"
href: docs/reference/cells/cells-jupyter.qmd
- text: "Knitr"
href: docs/reference/cells/cells-knitr.qmd
- text: "Observable"
href: docs/reference/cells/cells-ojs.qmd
- section: "Projects"
contents:
- text: "Options"
href: docs/reference/projects/options.qmd
- text: "Websites"
href: docs/reference/projects/websites.qmd
- text: "Books"
href: docs/reference/projects/books.qmd
- section: "More"
contents:
- text: "Dates"
href: docs/reference/dates.qmd
- text: "Globs"
href: docs/reference/globs.qmd
- text: "Citations"
href: docs/reference/metadata/citation.qmd
- id: prerelease
title: "Quarto 1.3"
contents:
- section: "Highlights"
href: docs/prerelease/1.3/index.qmd
contents:
- text: "Confluence Publishing"
href: docs/publishing/confluence.qmd
- text: "Multi-Format"
href: docs/output-formats/html-multi-format.qmd
- text: "Cell Embedding"
href: docs/authoring/notebook-embed.qmd
- text: "Grid Customization"
href: docs/output-formats/page-layout.qmd#grid-customization
- text: "Code Annotation"
href: docs/authoring/code-annotation.qmd
- section: "Quarto AST"
href: docs/prerelease/1.3/ast.qmd
contents:
- text: Callouts
href: docs/prerelease/1.3/custom-ast-nodes/callout.qmd
- text: Tabsets
href: docs/prerelease/1.3/custom-ast-nodes/tabset.qmd
- text: Conditional Blocks
href: docs/prerelease/1.3/custom-ast-nodes/conditional-block.qmd
- text: "Mermaid Theming"
href: docs/authoring/diagrams.qmd#mermaid-theming
- text: "PDF Images"
href: docs/prerelease/1.3/pdf.qmd
- text: "`kbd` Shortcode"
href: docs/authoring/markdown-basics.qmd#keyboard-shortcuts
bibliography: references.bib
format:
html:
toc: true
theme:
light: [cosmo, theme.scss]
code-copy: true
code-overflow: wrap
css: styles.css
include-after-body: js.html
grid:
sidebar-width: 250px
body-width: 900px
margin-width: 300px
filters:
- filters/tools-tabset.lua
freeze: true
editor: visual
profile:
group:
- [prerelease,rc]Quarto projects
Quarto projects have a
_quarto.ymlfileThe
typefield in this file indicates the type of project:default: Collection of documentswebsite: Websites (and blogs)book: Booksmanuscript: Manuscripts (Quarto 1.4+)
Quarto websites
Websites are essentially
format: html+ a Quarto Project fileBut a website is different than
format: htmlin that it has multiple pagesWebsites 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
Whole game
Let’s build a website that features the Jupyter notebook 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 GitHub Pages with
quarto publish
Your turn
- Add one more notebook that has at least one executable code cell and add it to the navigation list in
_quarto.ymland render your site.- Not inspired to generate content? Feel free to copy the contents of https://github.com/mine-cetinkaya-rundel/quarto-pydata-website-completed/blob/main/posts/islands-species.ipynb.
- Add an about page,
about.qmd, personalize it, and add it to the navigation list in_quarto.ymland render your site. - Re-publish on GitHub pages 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 your two 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.ymlfile.
- Don’t forget to make corresponding changes in your
Customizing your blog
Experiment with the style of listings and choose one you like.
05:00
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
freezeandcacheoptions give you fine control over these decisions
Freeze
- The
freezeoption controls when/if computational documents be re-rendered during a global project render:
The
freezeoption is typically added to a_metadata.ymlfile within a specific directory, affecting all files in that directory.For blogs, set
feezein_metadata.ymlat the root of thepostsdirectory.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 notebookTo execute the cells, pass the
--executeflag to render:
- Or specify this behavior within the notebook’s YAML front matter:
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)
cachecan 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, orfor files within a directory in
_metadata.ymlin that directory
- Cache option is typically set for a given file or for individual chunk(s) in a file.
or
Freezing
Add a _metadata.yml file to the posts directory of your website and update the YAML front matter of your blog posts to execute the cells when quarto rendering.
Wrap up
Learn more
Links for reviewing tutorial materials
- Slides: https://bit.ly/quarto-pydata
- If you’re interested, source code for slides: https://github.com/mine-cetinkaya-rundel/quarto-pydata-slides
- Starter repo: https://github.com/mine-cetinkaya-rundel/quarto-pydata-website
- Complete repo: https://github.com/mine-cetinkaya-rundel/quarto-pydata-website-completed
- Published website: https://mine-cetinkaya-rundel.github.io/quarto-pydata-website-completed
thank you!
any questions?
Acknowledgements
- Artwork by Allison Horst: https://allisonhorst.com/cetinkaya-rundel-lowndes-quarto-keynote
- Code examples from
palmerpenguins: https://github.com/mcnakhaee/palmerpenguins
