diff --git a/.gitignore b/.gitignore index 601cb26b..01c7ed4e 100644 --- a/.gitignore +++ b/.gitignore @@ -3,7 +3,6 @@ wip .DS_Store */.DS_Store .Rproj.user -cheatsheets.Rproj .Rhistory .RData rsconnect/ diff --git a/_freeze/html/quarto/execute-results/html.json b/_freeze/html/quarto/execute-results/html.json new file mode 100644 index 00000000..53b9dbb9 --- /dev/null +++ b/_freeze/html/quarto/execute-results/html.json @@ -0,0 +1,14 @@ +{ + "hash": "bcf58e7473223cdb5ba43bb16c3e8981", + "result": { + "markdown": "---\ntitle: \"Publish and Share with Quarto :: Cheatsheet\"\ndescription: \"QMD Edition\"\nimage-alt: \"\"\nengine: knitr\nexecute:\n eval: true\n output: false\n warning: false\ncode-overflow: wrap\n---\n\n\n::: column-margin\n\n```{=html}\n\"Hex\n

\n```\n\n:::\n\n\n::: {.cell .column-margin}\n\n

Download PDF

\n\"\"/\n\n

\n:::\n\n\n## Overview\n\n![](images/quarto-illustration.png){fig-alt=\"A schematic representing the multi-language input (e.g. Python, R, Observable, Julia) and multi-format output (e.g. PDF, html, Word documents, and more) versatility of Quarto.\"}[^credit] \n\n[^credit]: Artwork from \"Hello, Quarto\" keynote by Julia Lowndes and Mine Çetinkaya-Rundel, presented at RStudio Conference 2022. Illustrated by [Allison Horst](https://allisonhorst.com/allison-horst).\n\n* **Author**: Write and code in plain text. Author documents as .qmd files, or Jupyter notebooks. Write in a rich Markdown syntax.\n\n* **Render**: Generate documents, presentations and more. Produce HTML, PDF, MS Word, reveal.js, MS Powerpoint, Beamer, websites, blogs, books...\n\n* **Share**: Share your work with the world. Quickly deploy to GitHub Pages, Netlify, Quarto Pub, Posit Cloud, or Posit Connect.\n\n### Get Quarto\n\nGet Quarto from: \n\nOr, use version **bundled with RStudio.**\n\n### Get Started\n\n\n\n## Author\n\n### Source File: hello.qmd\n\n````{.markdown}\n---\ntitle: \"Hello, Penguins\"\nformat: html\nexecute:\n echo: false\n---\n\n## Meet the penguins\n\nThe `penguins` data contains size measurements for \npenguins from three islands in the Palmer Archipelago, \nAntarctica.\n\nThe three species of penguins have quite distinct \ndistributions of physical dimensions (@fig-penguins).\n\n```{{r}}\n#| label: fig-penguins\n#| fig-cap: \"Dimensions of penguins across three species.\"\n#| warning: false\nlibrary(tidyverse, quietly = TRUE)\nlibrary(palmerpenguins)\npenguins |>\n ggplot(aes(x = flipper_length_mm, y = bill_length_mm)) +\n geom_point(aes(color = species)) +\n scale_color_manual(\n values = c(\"darkorange\", \"purple\", \"cyan4\")) +\n theme_minimal()\n```\n````\n\n### Highlights in the source file\n\n* Set format(s) and options. Use YAML Syntax.\n \n ```` markdown\n ---\n title: \"Hello, Penguins\"\n format: html\n execute:\n echo: false\n ---\n ````\n\n* `## Write with **Markdown**` \n \n **RStudio**: Help > Markdown Quick Reference\n \n RStudio & VS Code: Use the **Visual Editor**\n\n ```` markdown\n ## Meet the penguins\n \n The `penguins` data contains size measurements for \n penguins from three islands in the Palmer Archipelago, \n Antarctica.\n \n The three species of penguins have quite distinct \n distributions of physical dimensions (@fig-penguins).\n ````\n \n* Include code. R, Python, Julia, Observable, or any language with a Jupyter kernel.\n\n ````markdown\n ```{{r}}\n #| label: fig-penguins\n #| fig-cap: \"Dimensions of penguins across three species.\"\n #| warning: false\n library(tidyverse, quietly = TRUE)\n library(palmerpenguins)\n penguins |>\n ggplot(aes(x = flipper_length_mm, y = bill_length_mm)) +\n geom_point(aes(color = species)) +\n scale_color_manual(\n values = c(\"darkorange\", \"purple\", \"cyan4\")) +\n theme_minimal()\n ```\n ````\n\n### Use a tool with a rich authoring experience\n\n[RStudio](https://posit.co/products/open-source/rstudio/), or \n[Visual Studio Code](https://code.visualstudio.com/) + [Quarto extension](https://marketplace.visualstudio.com/items?itemName=quarto.quarto)\n\n* **Run** code cells as you write\n* **Render** with a button or keyboard shortcut\n* Edit Quarto documents with a **Visual Editor** \n \n ![](images/quarto-visual-editor.png){fig-alt=\"Screenshot of the Visual Editor toolbar. Toolbar shows menu items: Normal with dropdown, bold, italics, code, bulleted list, numbered list, link, image, Format dropdown, Insert dropdown and Table dropdown.\"}\n \n - Apply formatting in Visual Editor. Saved as Markdown in source.\n \n - Insert elements like code cells, cross references, and more.\n\n### Or any text editor\n\nQuarto documents (.qmd) can be edited in any tool that edits text.\n\n## Render\n\n**Save,** then render to **preview** the document output. \n\n```{.bash filename=\"Terminal\"}\nquarto preview hello.qmd\n```\n\nRStudio & VS Code: Use **Render** button\n\nThe resulting HTML/PDF/MS Word/etc. document will be created and saved in the same directory as the source .qmd file.\n\n### Rendered output: hello.html\n\n![](images/quarto-rendered-output.png){fig-alt=\"Screenshot of a webpage with the title 'Hello, Penguins'. There is a subheading 'Meet the penguins' followed by a paragraph of text including a link to 'Figure 1', then a scatterplot.\"}\n\n### Highlights in the rendered output\n\n* Features for scientific publishing. Cross references, citations, equations, and more.\n\n* Output integrated into document. Control how output appears with special comments in your code.\n\n### Behind the Scenes\n\nWhen you render a document, Quarto:\n\n1. Runs the code and embeds results and text into an .md file with:\n - **Knitr**, if any `{r}` cells, or\n - **Jupyter**, if any other cells.\n \n2. Converts the .md file into the output format with Pandoc.\n\n## Publish\n\n``` {.bash filename=\"Terminal\"}\nquarto publish {venue} hello.qmd\n```\n\n`{venue}`: quarto-pub, connect, gh-pages, netlify, confluence, (*v1.4*) posit-cloud\n\nRStudio: Use **Publish** button ![](images/quarto-rstudio-publish.png){fig-alt=\"Publish button icon in RStudio\" width=\"10%\"}\n\n- [**Quarto Pub**](https://quartopub.com/) Free publishing service for Quarto content.\n\n- [**Posit Cloud**](https://posit.cloud/) Cloud-hosted, control access to project and output. ![](images/quarto-rstudio-publish.png){fig-alt=\"Push button publishing from RStudio\" width=\"10%\"}\n\n- [**Posit Connect**](https://posit.co/products/enterprise/connect/) Org-hosted, control access, schedule updates. ![](images/quarto-rstudio-publish.png){fig-alt=\"Push button publishing from RStudio\" width=\"10%\"}\n\n## Quarto Projects\n\n### Create websites, books and more\n\nA directory of Quarto documents + a configuration file (`_quarto.yml`)\n\nSee examples at: \n\nGet started from the command line:\n\n``` {.bash filename=\"Terminal\"}\nquarto create project {type}\n```\n\n`{type}`: default, website, blog, book, confluence, (*v1.4*) manuscript\n\nRStudio: Use **File** \\> **New Project**\n\n## Include Code\n\n### Code Cells\n\nCode cells start with ```` ```{language} ````, and end with ```` ``` ````.\n\nRStudio & VS Code: Use **Insert Code Chunk/Cell**.\n\n::: {layout-ncol=\"2\"}\n```{{r}}\n#| label: chunk-id\n```\n\n```{{python}}\n#| label: chunk-id\n```\n:::\n\nOther languages: `{julia}`, `{ojs}`\n\nAdd code cell options with `#|` comments.\n\nCell options control [**execution**](#execution), [figures](#figures), [tables](#tables), layout and more. See them all at: \n\n### Execution Options {#execution}\n\n+-----------+-----------+----------------------------------------------------------+\n| Option | Default | Effects |\n+===========+===========+==========================================================+\n| `echo` | `true` | `false`: hide code in output\\ |\n| | | `fenced`: include code cell syntax |\n+-----------+-----------+----------------------------------------------------------+\n| `eval` | `true` | `false`: don't run code |\n+-----------+-----------+----------------------------------------------------------+\n| `include` | `true` | `false`: don't include code or results |\n+-----------+-----------+----------------------------------------------------------+\n| `output` | `true` | `false`: don't include results\\ |\n| | | `asis`: treat results as raw markdown |\n+-----------+-----------+----------------------------------------------------------+\n| `warning` | `true` | `false`: don't include warnings in output |\n+-----------+-----------+----------------------------------------------------------+\n| `error` | `false` | `true`: include error in output and continue with render |\n+-----------+-----------+----------------------------------------------------------+\n\nSet execution options at the **cell level**:\n\n::: {layout-ncol=\"2\"}\n```{{r}}\n#| echo: false\n```\n\n```{{python}}\n#| echo: false\n```\n:::\n\nSet options in code cells with `#|` comments and YAML syntax: `key: value`.\n\nOr globally in the YAML header with the **execute** option:\n\n``` yaml\n---\nexecute:\n echo: false\n---\n```\n\n### Inline Code\n\nUse computed values directly in text sections. Code is evaluated at render and results appear as text.\n\n::: {layout-ncol=\"3\"}\n
\n\n#### Knitr\n\nValue is `` `r 2 + 2` ``.\n\n
\n\n
\n\n#### Jupyter\n\n[v1.4]{.small .muted}\n\nValue is `` `{python} 2 + 2` ``.\n\n
\n\n
\n\n#### Output\n\nValue is 4.\n\n
\n:::\n\n## Set Formats and Options\n\n::: {layout-ncol=2}\n\n::: {#set-options}\n### Set Format Options\n\n``` yaml\n---\ntitle: \"My Document\"\nformat: \n html: \n code-fold: true\n toc: true\n---\n```\n\n- Indent format 2 spaces\n- Indent options 4 spaces\n:::\n\n::: {#multiple-formats}\n\n### Multiple Formats\n\n``` yaml\n---\ntitle: \"My Document\"\ntoc: true\nformat: \n html: \n code-fold: true\n pdf: default\n---\n```\n\n- Top-level options (e.g. `toc`) apply to all formats\n\n:::\n:::\n\nCommon values for `format`: html, pdf[^2], docx, odt, rtf, gfm, pptx, revealjs, beamer[^3]\n\n[^2]: PDFs and Beamer slides require LaTeX, use:\n\n ``` {.bash filename=\"Terminal\"}\n quarto install tinytex\n ```\n\n[^3]: PDFs and Beamer slides require LaTeX, use:\n\n ``` {.bash filename=\"Terminal\"}\n quarto install tinytex\n ```\n\n\nRender **all** formats:\n\n``` {.bash filename=\"Terminal\"}\nquarto render hello.qmd\n```\n\nRender a **specific** format:\n\n``` {.bash filename=\"Terminal\"}\nquarto render hello.qmd --to pdf\n```\n\n\n### Output Options Table\n\n\n::: {.cell tbl-cap='Important Options. The first column is the option name, an \"X\" in the next three columns indicates whether the option applies to the format, the fourth column decribes the options and possible values, the final column indicates whether the options can also be set in a code cell.'}\n::: {.cell-output-display}\n```{=html}\n
\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n\n\n\n\n \n\n\n\n\n\n \n\n\n\n\n\n \n \n \n \n\n\n\n\n\n \n\n\n\n\n\n \n\n\n\n\n\n \n\n\n\n\n\n \n\n\n\n\n\n \n \n \n \n\n\n\n\n\n \n\n\n\n\n\n \n \n \n \n\n\n\n\n\n \n\n\n\n\n\n \n\n\n\n\n\n \n \n \n \n\n\n\n\n\n \n\n\n\n\n\n \n\n\n\n\n\n \n \n \n \n\n\n\n\n\n \n\n\n\n\n\n \n\n\n\n\n\n \n \n \n
Optionhtml/revealjspdf/beamerdocx/pptxDescriptioncell level?
Navigation
tocXXX

Add a table of contents (true or false)

\n
toc-depthXXX

Lowest level of headings to add to table of contents (e.g. 2, 3)

\n
anchor-sectionsX

Show section anchors on mouse hover (true or false)

\n
Style
highlight-styleXXX

Syntax highlighting theme (e.g. arrow, pygments, kate, zenburn)

\n
mainfont, monofontXX

Font name. HTML: sets CSS font-family; LaTeX: via fontspec package

\n
themeX

Bootswatch theme name (e.g. cosmo, darkly, solar etc.)

\n
cssX

CSS or SCSS file to use to style the document (e.g. “style.css”)

\n
reference-docX

docx/pptx file containing template styles (e.g. file.docx, file.pptx)

\n
NA
include-in-headerXX

Files of content to include in header of output document, also include-before-body, include-after-body

\n
keep-mdXXX

Keep intermediate files (true or false), also keep-tex, keep-ipynb

\n
LaTeX
documentclassX

LaTeX document class, set document options with classoption

\n
pdf-engineX

LaTeX engine to produce PDF output (xelatex, pdflatex, lualatex)

\n
cite-methodX

Method used to format citations (citeproc, natbib, biblatex)

\n
Code
code-foldX

Let readers toggle the display of R code (false, true, or show)

\n
X
code-toolsX

Add menu for hiding, showing, and downloading code (true or false)

\n
code-overflowX

Display of wide code (scroll, or wrap)

\n
X
Figures
fig-alignXXdocx only

Alignment of figures (default, left, right, center)

\n
X
fig-width, fig-heightXXX

Default width and height for figures in inches

\n
Knitr only
fig-formatXXX

Format for Matplotlib or R figures (retina, png, jpeg, svg, or pdf)

\n
\n
\n```\n:::\n:::\n\n\nVisit to see all options by format\n\n\n## Add Content\n\n### Figures {#figures}\n\n#### Markdown\n\n``` markdown\n![CAP](image.png){#fig-LABEL fig-alt=\"ALT\"}\n```\n\n#### Computation\n\n```{{python}}\n#| label: fig-LABEL\n#| fig-cap: CAP\n#| fig-alt: ALT\n{{ plot code here }}\n```\n\nOr `{r}`\n\n### Tables {#tables}\n\n#### Markdown\n\n``` markdown\n|object | radius|\n|:------|------:|\n|Sun | 696000|\n|Earth | 6371|\n\n: CAPTION {#tbl-LABEL}\n```\n\n#### Computation\n\nOutput a markdown table or an HTML table from your code.\n\n::: {layout-ncol=\"2\"}\n
\n\n##### Knitr\n\nUse `knitr::kable()` to produce markdown:\n\n```{{r}}\n#| label: tbl-LABEL\n#| tbl-cap: CAPTION\n\nknitr::kable(head(cars))\n```\n\nAlso see the R packages: gt, flextable, kableExtra.\n\n
\n\n
\n\n##### Jupyter\n\nAdd `Markdown()` to Markdown output:\n\n```{{python}}\n#| label: tbl-LABEL\n#| tbl-cap: CAPTION\nimport pandas as pd, tabulate\nfrom IPython.display import Markdown\ndf = pd.DataFrame({\"A\": [1, 2], \n \"B\": [1, 2]})\nMarkdown(df.to_markdown(index=False))\n```\n\n
\n:::\n\n\n### Cross References\n\n1. **Add labels:**\n\n - **Code cell:** add option `label: prefix-LABEL`\n - **Markdown:** add attribute `#prefix-LABEL`\n\n2. **Add references:** `@prefix-LABEL`, e.g.\n\n ``` markdown\n You can see in @fig-scatterplot, that...\n ```\n\n| `prefix` | Renders |\n|----------|------------|\n| `fig-` | Figure 1 |\n| `tbl-` | Table 1 |\n| `eq-` | Equation 1 |\n| `sec-` | Section 1 |\n\n### Citations\n\n1. Add bibliography **file** to the YAML header:\n\n ``` yaml\n ---\n bibliography: references.bib\n ---\n ```\n\n2. Add citations: `[@citation]`, or `@citation`\n\nRStudio & VS Code: Use **Insert Citations** dialog in the Visual Editor. \nBuild your bibliography file from your Zotero library, DOI, Crossref, DataCite, or PubMed.\n\n### Callouts\n\n``` markdown\n::: {.callout-tip}\n## Title\n\nText\n:::\n```\n\nInstead of `tip` use one of: `note`, `caution`, `warning`, or `important`:\n\n::: callout-tip\n## tip\n:::\n\n::: callout-note\n## note\n:::\n\n::: callout-caution\n## caution\n:::\n\n::: callout-warning\n## warning\n:::\n\n::: callout-important\n## important\n:::\n\n### Shortcodes\n\n``` {.markdown shortcodes=\"false\"}\n{{< include _file.qmd >}} \n```\n\n``` {.markdown shortcodes=\"false\"}\n{{< embed file.ipynb#id >}}\n```\n\n``` {.markdown shortcodes=\"false\"}\n{{< video video.mp4 >}}\n```\n\n------------------------------------------------------------------------\n\nCC BY SA Posit Software, PBC • [info\\@posit.co](mailto:info@posit.co) • [posit.co](https://posit.co)\n\nLearn more at [quarto.org](https://quarto.org).\n\nQuarto 1.3\n\nUpdated: 2023-08.\n\n------------------------------------------------------------------------\n", + "supporting": [], + "filters": [ + "rmarkdown/pagebreak.lua" + ], + "includes": {}, + "engineDependencies": {}, + "preserve": {}, + "postProcess": true + } +} \ No newline at end of file diff --git a/cheatsheets.Rproj b/cheatsheets.Rproj new file mode 100644 index 00000000..989710df --- /dev/null +++ b/cheatsheets.Rproj @@ -0,0 +1,17 @@ +Version: 1.0 + +RestoreWorkspace: Default +SaveWorkspace: Default +AlwaysSaveHistory: Default + +EnableCodeIndexing: Yes +UseSpacesForTab: Yes +NumSpacesForTab: 2 +Encoding: UTF-8 + +RnwWeave: Sweave +LaTeX: pdfLaTeX + +BuildType: None + +MarkdownWrap: Sentence diff --git a/html/data/format-options.csv b/html/data/format-options.csv new file mode 100644 index 00000000..f7dd4f94 --- /dev/null +++ b/html/data/format-options.csv @@ -0,0 +1,20 @@ +Category,Option,Description,html/revealjs,pdf/beamer,docx/pptx,cell level? +Navigation,toc,Add a table of contents (true or false),X,X,X, +Navigation,toc-depth,"Lowest level of headings to add to table of contents (e.g. 2, 3)",X,X,X, +Navigation,anchor-sections,Show section anchors on mouse hover (true or false),X,,, +Style,highlight-style,"Syntax highlighting theme (e.g. arrow, pygments, kate, zenburn)",X,X,X, +Style,"mainfont, monofont",Font name. HTML: sets CSS `font-family`; LaTeX: via fontspec package,X,X,, +Style,theme,"Bootswatch theme name (e.g. cosmo, darkly, solar etc.)",X,,, +Style,css,"CSS or SCSS file to use to style the document (e.g. ""style.css"")",X,,, +Style,reference-doc,"docx/pptx file containing template styles (e.g. file.docx, file.pptx)",,,X, +,include-in-header,"Files of content to include in header of output document, also **include-before-body**, **include-after-body**",X,X,, +,keep-md,"Keep intermediate files (true or false), also **keep-tex**, **keep-ipynb**",X,X,X, +LaTeX,documentclass,"LaTeX document class, set document options with **classoption**",,X,, +LaTeX,pdf-engine,"LaTeX engine to produce PDF output (xelatex, pdflatex, lualatex)",,X,, +LaTeX,cite-method,"Method used to format citations (citeproc, natbib, biblatex)",,X,, +Code,code-fold,"Let readers toggle the display of R code (false, true, or show)",X,,,X +Code,code-tools,"Add menu for hiding, showing, and downloading code (true or false)",X,,, +Code,code-overflow,"Display of wide code (scroll, or wrap)",X,,,X +Figures,fig-align,"Alignment of figures (default, left, right, center)",X,X,docx only,X +Figures,"fig-width, fig-height",Default width and height for figures in inches,X,X,X,Knitr only +Figures,fig-format,"Format for Matplotlib or R figures (retina, png, jpeg, svg, or pdf)",X,X,X, \ No newline at end of file diff --git a/html/images/logo-quarto.png b/html/images/logo-quarto.png new file mode 100644 index 00000000..fafec19a Binary files /dev/null and b/html/images/logo-quarto.png differ diff --git a/html/images/quarto-illustration.png b/html/images/quarto-illustration.png new file mode 100644 index 00000000..63a9ca5d Binary files /dev/null and b/html/images/quarto-illustration.png differ diff --git a/html/images/quarto-rendered-output.png b/html/images/quarto-rendered-output.png new file mode 100644 index 00000000..597b616d Binary files /dev/null and b/html/images/quarto-rendered-output.png differ diff --git a/html/images/quarto-rstudio-publish.png b/html/images/quarto-rstudio-publish.png new file mode 100644 index 00000000..1e6934c0 Binary files /dev/null and b/html/images/quarto-rstudio-publish.png differ diff --git a/html/images/quarto-visual-editor.png b/html/images/quarto-visual-editor.png new file mode 100644 index 00000000..f2e7dd71 Binary files /dev/null and b/html/images/quarto-visual-editor.png differ diff --git a/html/quarto.qmd b/html/quarto.qmd new file mode 100644 index 00000000..950bc2bb --- /dev/null +++ b/html/quarto.qmd @@ -0,0 +1,589 @@ +--- +title: "Publish and Share with Quarto :: Cheatsheet" +description: "QMD Edition" +image-alt: "" +engine: knitr +execute: + eval: true + output: false + warning: false +code-overflow: wrap +--- + +::: column-margin +```{=html} +Hex logo for Quarto - a white circle segmented into quarters next to the text Quarto on a blue background. +

+``` +::: + +```{r} +#| output: asis +#| echo: false +#| column: margin +source("common.R") +sheet_name <- tools::file_path_sans_ext(knitr::current_input()) +pdf_preview_link(sheet_name) +translation_list(sheet_name) +``` + +## Overview + +![](images/quarto-illustration.png){fig-alt="A schematic representing the multi-language input (e.g. Python, R, Observable, Julia) and multi-format output (e.g. PDF, html, Word documents, and more) versatility of Quarto."}[^credit] + +[^credit]: Artwork from "Hello, Quarto" keynote by Julia Lowndes and Mine Çetinkaya-Rundel, presented at RStudio Conference 2022. Illustrated by [Allison Horst](https://allisonhorst.com/allison-horst). + +* **Author**: Write and code in plain text. Author documents as .qmd files, or Jupyter notebooks. Write in a rich Markdown syntax. + +* **Render**: Generate documents, presentations and more. Produce HTML, PDF, MS Word, reveal.js, MS Powerpoint, Beamer, websites, blogs, books... + +* **Share**: Share your work with the world. Quickly deploy to GitHub Pages, Netlify, Quarto Pub, Posit Cloud, or Posit Connect. + +### Get Quarto + +Get Quarto from: + +Or, use version **bundled with RStudio.** + +### Get Started + + + +## Author + +### Source File: hello.qmd + +````{.markdown} +--- +title: "Hello, Penguins" +format: html +execute: + echo: false +--- + +## Meet the penguins + +The `penguins` data contains size measurements for +penguins from three islands in the Palmer Archipelago, +Antarctica. + +The three species of penguins have quite distinct +distributions of physical dimensions (@fig-penguins). + +```{{r}} +#| label: fig-penguins +#| fig-cap: "Dimensions of penguins across three species." +#| warning: false +library(tidyverse, quietly = TRUE) +library(palmerpenguins) +penguins |> + ggplot(aes(x = flipper_length_mm, y = bill_length_mm)) + + geom_point(aes(color = species)) + + scale_color_manual( + values = c("darkorange", "purple", "cyan4")) + + theme_minimal() +``` +```` + +### Highlights in the source file + +* Set format(s) and options. Use YAML Syntax. + + ```` markdown + --- + title: "Hello, Penguins" + format: html + execute: + echo: false + --- + ```` + +* `## Write with **Markdown**` + + **RStudio**: Help > Markdown Quick Reference + + RStudio & VS Code: Use the **Visual Editor** + + ```` markdown + ## Meet the penguins + + The `penguins` data contains size measurements for + penguins from three islands in the Palmer Archipelago, + Antarctica. + + The three species of penguins have quite distinct + distributions of physical dimensions (@fig-penguins). + ```` + +* Include code. R, Python, Julia, Observable, or any language with a Jupyter kernel. + + ````markdown + ```{{r}} + #| label: fig-penguins + #| fig-cap: "Dimensions of penguins across three species." + #| warning: false + library(tidyverse, quietly = TRUE) + library(palmerpenguins) + penguins |> + ggplot(aes(x = flipper_length_mm, y = bill_length_mm)) + + geom_point(aes(color = species)) + + scale_color_manual( + values = c("darkorange", "purple", "cyan4")) + + theme_minimal() + ``` + ```` + +### Use a tool with a rich authoring experience + +[RStudio](https://posit.co/products/open-source/rstudio/), or +[Visual Studio Code](https://code.visualstudio.com/) + [Quarto extension](https://marketplace.visualstudio.com/items?itemName=quarto.quarto) + +* **Run** code cells as you write +* **Render** with a button or keyboard shortcut +* Edit Quarto documents with a **Visual Editor** + + ![](images/quarto-visual-editor.png){fig-alt="Screenshot of the Visual Editor toolbar. Toolbar shows menu items: Normal with dropdown, bold, italics, code, bulleted list, numbered list, link, image, Format dropdown, Insert dropdown and Table dropdown."} + + - Apply formatting in Visual Editor. Saved as Markdown in source. + + - Insert elements like code cells, cross references, and more. + +### Or any text editor + +Quarto documents (.qmd) can be edited in any tool that edits text. + +## Render + +**Save,** then render to **preview** the document output. + +```{.bash filename="Terminal"} +quarto preview hello.qmd +``` + +RStudio & VS Code: Use **Render** button + +The resulting HTML/PDF/MS Word/etc. document will be created and saved in the same directory as the source .qmd file. + +### Rendered output: hello.html + +![](images/quarto-rendered-output.png){fig-alt="Screenshot of a webpage with the title 'Hello, Penguins'. There is a subheading 'Meet the penguins' followed by a paragraph of text including a link to 'Figure 1', then a scatterplot."} + +### Highlights in the rendered output + +* Features for scientific publishing. Cross references, citations, equations, and more. + +* Output integrated into document. Control how output appears with special comments in your code. + +### Behind the Scenes + +When you render a document, Quarto: + +1. Runs the code and embeds results and text into an .md file with: + - **Knitr**, if any `{r}` cells, or + - **Jupyter**, if any other cells. + +2. Converts the .md file into the output format with Pandoc. + +## Publish + +``` {.bash filename="Terminal"} +quarto publish {venue} hello.qmd +``` + +`{venue}`: quarto-pub, connect, gh-pages, netlify, confluence, (*v1.4*) posit-cloud + +RStudio: Use **Publish** button ![](images/quarto-rstudio-publish.png){fig-alt="Publish button icon in RStudio" width="10%"} + +- [**Quarto Pub**](https://quartopub.com/) Free publishing service for Quarto content. + +- [**Posit Cloud**](https://posit.cloud/) Cloud-hosted, control access to project and output. ![](images/quarto-rstudio-publish.png){fig-alt="Push button publishing from RStudio" width="10%"} + +- [**Posit Connect**](https://posit.co/products/enterprise/connect/) Org-hosted, control access, schedule updates. ![](images/quarto-rstudio-publish.png){fig-alt="Push button publishing from RStudio" width="10%"} + +## Quarto Projects + +### Create websites, books and more + +A directory of Quarto documents + a configuration file (`_quarto.yml`) + +See examples at: + +Get started from the command line: + +``` {.bash filename="Terminal"} +quarto create project {type} +``` + +`{type}`: default, website, blog, book, confluence, (*v1.4*) manuscript + +RStudio: Use **File** \> **New Project** + +## Include Code + +### Code Cells + +Code cells start with ```` ```{language} ````, and end with ```` ``` ````. + +RStudio & VS Code: Use **Insert Code Chunk/Cell**. + +::: {layout-ncol="2"} +```{{r}} +#| label: chunk-id +``` + +```{{python}} +#| label: chunk-id +``` +::: + +Other languages: `{julia}`, `{ojs}` + +Add code cell options with `#|` comments. + +Cell options control [**execution**](#execution), [figures](#figures), [tables](#tables), layout and more. See them all at: + +### Execution Options {#execution} + ++-----------+-----------+----------------------------------------------------------+ +| Option | Default | Effects | ++===========+===========+==========================================================+ +| `echo` | `true` | `false`: hide code in output\ | +| | | `fenced`: include code cell syntax | ++-----------+-----------+----------------------------------------------------------+ +| `eval` | `true` | `false`: don't run code | ++-----------+-----------+----------------------------------------------------------+ +| `include` | `true` | `false`: don't include code or results | ++-----------+-----------+----------------------------------------------------------+ +| `output` | `true` | `false`: don't include results\ | +| | | `asis`: treat results as raw markdown | ++-----------+-----------+----------------------------------------------------------+ +| `warning` | `true` | `false`: don't include warnings in output | ++-----------+-----------+----------------------------------------------------------+ +| `error` | `false` | `true`: include error in output and continue with render | ++-----------+-----------+----------------------------------------------------------+ + +Set execution options at the **cell level**: + +::: {layout-ncol="2"} +```{{r}} +#| echo: false +``` + +```{{python}} +#| echo: false +``` +::: + +Set options in code cells with `#|` comments and YAML syntax: `key: value`. + +Or globally in the YAML header with the **execute** option: + +``` yaml +--- +execute: + echo: false +--- +``` + +### Inline Code + +Use computed values directly in text sections. Code is evaluated at render and results appear as text. + +::: {layout-ncol="3"} +
+ +#### Knitr + +Value is `` `r knitr::inline_expr("2 + 2")` ``. + +
+ +
+ +#### Jupyter + +[v1.4]{.small .muted} + +Value is `` `{python} 2 + 2` ``. + +
+ +
+ +#### Output + +Value is `r 2*2`. + +
+::: + +## Set Formats and Options + +::: {layout-ncol=2} + +::: {#set-options} +### Set Format Options + +``` yaml +--- +title: "My Document" +format: + html: + code-fold: true + toc: true +--- +``` + +- Indent format 2 spaces +- Indent options 4 spaces +::: + +::: {#multiple-formats} + +### Multiple Formats + +``` yaml +--- +title: "My Document" +toc: true +format: + html: + code-fold: true + pdf: default +--- +``` + +- Top-level options (e.g. `toc`) apply to all formats + +::: +::: + +Common values for `format`: html, pdf[^2], docx, odt, rtf, gfm, pptx, revealjs, beamer[^3] + +[^2]: PDFs and Beamer slides require LaTeX, use: + + ``` {.bash filename="Terminal"} + quarto install tinytex + ``` + +[^3]: PDFs and Beamer slides require LaTeX, use: + + ``` {.bash filename="Terminal"} + quarto install tinytex + ``` + + +Render **all** formats: + +``` {.bash filename="Terminal"} +quarto render hello.qmd +``` + +Render a **specific** format: + +``` {.bash filename="Terminal"} +quarto render hello.qmd --to pdf +``` + + +### Output Options Table + +```{r} +#| echo: false +#| output: true +#| tbl-cap: Important Options. The first column is the option name, an "X" in the next three columns indicates whether the option applies to the format, the fourth column decribes the options and possible values, the final column indicates whether the options can also be set in a code cell. +library(readr) +library(dplyr) +library(gt) +format_options <- read_csv("data/format-options.csv") +format_options |> + group_by(Category) |> + select(Category, Option, `html/revealjs`, `pdf/beamer`, `docx/pptx`, Description, `cell level?`) |> + gt() |> + sub_missing(missing_text = "") |> + fmt_markdown(columns = Description) |> + tab_style( + style = cell_text(weight = "bold"), + locations = cells_body( + columns = Option + )) |> + tab_style( + style = cell_fill(color = "gray95"), + locations = cells_body( + rows = Category %in% c("Navigation", NA, "Code") + ) + ) |> + opt_stylize(style=5, add_row_striping = FALSE) +``` + +Visit to see all options by format + + +## Add Content + +### Figures {#figures} + +#### Markdown + +``` markdown +![CAP](image.png){#fig-LABEL fig-alt="ALT"} +``` + +#### Computation + +```{{python}} +#| label: fig-LABEL +#| fig-cap: CAP +#| fig-alt: ALT +{{ plot code here }} +``` + +Or `{r}` + +### Tables {#tables} + +#### Markdown + +``` markdown +|object | radius| +|:------|------:| +|Sun | 696000| +|Earth | 6371| + +: CAPTION {#tbl-LABEL} +``` + +#### Computation + +Output a markdown table or an HTML table from your code. + +::: {layout-ncol="2"} +
+ +##### Knitr + +Use `knitr::kable()` to produce markdown: + +```{{r}} +#| label: tbl-LABEL +#| tbl-cap: CAPTION + +knitr::kable(head(cars)) +``` + +Also see the R packages: gt, flextable, kableExtra. + +
+ +
+ +##### Jupyter + +Add `Markdown()` to Markdown output: + +```{{python}} +#| label: tbl-LABEL +#| tbl-cap: CAPTION +import pandas as pd, tabulate +from IPython.display import Markdown +df = pd.DataFrame({"A": [1, 2], + "B": [1, 2]}) +Markdown(df.to_markdown(index=False)) +``` + +
+::: + + +### Cross References + +1. **Add labels:** + + - **Code cell:** add option `label: prefix-LABEL` + - **Markdown:** add attribute `#prefix-LABEL` + +2. **Add references:** `@prefix-LABEL`, e.g. + + ``` markdown + You can see in @fig-scatterplot, that... + ``` + +| `prefix` | Renders | +|----------|------------| +| `fig-` | Figure 1 | +| `tbl-` | Table 1 | +| `eq-` | Equation 1 | +| `sec-` | Section 1 | + +### Citations + +1. Add bibliography **file** to the YAML header: + + ``` yaml + --- + bibliography: references.bib + --- + ``` + +2. Add citations: `[@citation]`, or `@citation` + +RStudio & VS Code: Use **Insert Citations** dialog in the Visual Editor. +Build your bibliography file from your Zotero library, DOI, Crossref, DataCite, or PubMed. + +### Callouts + +``` markdown +::: {.callout-tip} +## Title + +Text +::: +``` + +Instead of `tip` use one of: `note`, `caution`, `warning`, or `important`: + +::: callout-tip +## tip +::: + +::: callout-note +## note +::: + +::: callout-caution +## caution +::: + +::: callout-warning +## warning +::: + +::: callout-important +## important +::: + +### Shortcodes + +``` {.markdown shortcodes="false"} +{{< include _file.qmd >}} +``` + +``` {.markdown shortcodes="false"} +{{< embed file.ipynb#id >}} +``` + +``` {.markdown shortcodes="false"} +{{< video video.mp4 >}} +``` + +------------------------------------------------------------------------ + +CC BY SA Posit Software, PBC • [info\@posit.co](mailto:info@posit.co) • [posit.co](https://posit.co) + +Learn more at [quarto.org](https://quarto.org). + +Quarto 1.3 + +Updated: `r format(Sys.Date(), "%Y-%m")`. + +------------------------------------------------------------------------ diff --git a/index.qmd b/index.qmd index a8f67037..9ee466ac 100644 --- a/index.qmd +++ b/index.qmd @@ -13,6 +13,7 @@ listing: - "strings.qmd" - "shiny.qmd" - "package-development.qmd" + - "quarto.qmd" - "rmarkdown.qmd" - "keras.qmd" - "plumber.qmd" diff --git a/keynotes/quarto.key b/keynotes/quarto.key new file mode 100644 index 00000000..ccc76b32 Binary files /dev/null and b/keynotes/quarto.key differ diff --git a/pngs/quarto.png b/pngs/quarto.png new file mode 100644 index 00000000..56734f6c Binary files /dev/null and b/pngs/quarto.png differ diff --git a/quarto.pdf b/quarto.pdf new file mode 100644 index 00000000..726030c2 Binary files /dev/null and b/quarto.pdf differ diff --git a/renv.lock b/renv.lock index ccf919a2..b2fc0489 100644 --- a/renv.lock +++ b/renv.lock @@ -938,6 +938,11 @@ ], "Hash": "fd7b97bd862a14297b0bb7ed28a3dada" }, + "gt": { + "Package": "gt", + "Version": "0.9.0", + "Source": "Repository" + }, "gtable": { "Package": "gtable", "Version": "0.3.3",