[1] 2
Duke University + Posit
Slides from Part 1: https://mine.quarto.pub/hello-quarto-niss/talk.html
Artwork from “Hello, Quarto” keynote by Julia Lowndes and Mine Çetinkaya-Rundel, presented at RStudio Conference 2022. Illustrated by Allison Horst.
unifies + extends the R Markdown ecosystem
unifies + extends the R Markdown ecosystem
unifies for people who love R Markdown
unifies + extends the R Markdown ecosystem
unifies for people who love R Markdown
extends for people who don’t know R Markdown
These materials are pitched at someone who:
know some R + Quarto
has worked in RStudio
wants to learn about Quarto
I’ll teach you
More Quarto
How to create a website with Quarto
How to publish your website
Three components:
Metadata: YAML
Text: Markdown
Code: Executed via jupyter or knitr
Weave it all together, and you have beautiful, powerful, and useful outputs!
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
A YAML file with particular keys and values that Quarto recognizes. Unrecognized keys are ignored.
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 have a _quarto.yml file
The type field in this file indicates the type of project:
default: Collection of documents
website: Websites (and blogs)
book: Books
manuscript: Manuscripts (Quarto 1.4+)
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
Let’s build a website starting with a single .qmd file!
index.qmd_quarto.ymlprojects.qmdnavbar, sidebarquarto publishNote
If you’d like to follow along, create your repo based on the template at https://github.com/mine-cetinkaya-rundel/quarto-niss-websites-demo, clone it locally, and open it in RStudio.
Make your landing (index.qmd) page into an about page, about.qmd, personalize it, and add it to the navigation list in _quarto.yml and render your site.
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
Let’s now add a blog component to our website:
.qmd files with some “analysis” (code chunks) in them..qmd files in a new blog page using the listings feature.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 option controls when/if computational documents be re-rendered during a global project 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.
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:
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 option is typically set
for the whole website in _quarto.yml, or
for files within a directory in _metadata.yml in that directory
or
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 rendering your project.
thank you!
any questions?
palmerpenguins: https://github.com/mcnakhaee/palmerpenguins