quarto-dev · cwickham · May 30, 2025 · May 30, 2025 · Jun 11, 2025
diff --git a/Pipfile b/Pipfile
@@ -27,6 +27,8 @@ plotly = "*"
 pathlib = "*"
 nbformat = "*"
 statsmodels = "*"
+plotnine = "*"
+palmerpenguins = "*"
 
 [dev-packages]
 

diff --git a/Pipfile.lock b/Pipfile.lock
diff --git a/docs/get-started/_tool-chooser.md b/docs/get-started/_tool-chooser.md
@@ -1,6 +1,11 @@
 ```{=html}
 <ul id="choose-your-tool" class="nav nav-tabs" role="tablist">
   <h3 class="no-anchor">Choose your tool</h3>
+  <li class="nav-item" role="presentation">
+    <a class="nav-link" href="positron.html">
+      <img src="../images/positron-logo.svg">Positron
+    </a>
+  </li>
   <li class="nav-item" role="presentation">
     <a class="nav-link" href="vscode.html">
       <img src="../images/vscode-logo.png">VS Code

diff --git a/docs/get-started/hello/_positron/.gitignore b/docs/get-started/hello/_positron/.gitignore
@@ -0,0 +1,2 @@
+*.html
+*_files/
diff --git a/docs/get-started/hello/_positron/python/hello.qmd b/docs/get-started/hello/_positron/python/hello.qmd
@@ -0,0 +1,44 @@
+---
+title: "Hello, Quarto"
+format: html
+---
+
+```{python}
+#| label: load-packages
+#| include: false
+
+from plotnine import *
+from palmerpenguins import load_penguins
+
+penguins = load_penguins()
+```
+
+## Meet Quarto
+
+Quarto enables you to weave together content and executable code into a finished document. To learn more about Quarto see <https://quarto.org>.
+
+## Meet the penguins
+
+![](lter_penguins.png){style="float:right;" fig-alt="Illustration of three species of Palmer Archipelago penguins: Chinstrap, Gentoo, and Adelie. Artwork by @allison_horst." width="401"}
+
+The `penguins` data from the [**palmerpenguins**](https://allisonhorst.github.io/palmerpenguins "palmerpenguins python package") package contains size measurements for `{python} len(penguins)` penguins from three species observed on three islands in the Palmer Archipelago, Antarctica.
+
+The plot below shows the relationship between flipper and bill lengths of these penguins.
+
+```{python}
+#| label: plot-penguins
+#| warning: false
+#| echo: false
+
+(ggplot(penguins, 
+       aes(x='flipper_length_mm', y='bill_length_mm')) +
+  geom_point(aes(color='species', shape='species')) +
+  scale_color_manual(values=["#FF8C00","#A020F0","#008B8B"]) +
+  labs(
+    title="Flipper and bill length",
+    subtitle="Dimensions for penguins at Palmer Station LTER",
+    x="Flipper length (mm)", y="Bill length (mm)",
+    color="Penguin species", shape="Penguin species"
+  ) +
+  theme_minimal())
+```
diff --git a/docs/get-started/hello/_positron/python/lter_penguins.png b/docs/get-started/hello/_positron/python/lter_penguins.png
diff --git a/docs/get-started/hello/_positron/r/hello.qmd b/docs/get-started/hello/_positron/r/hello.qmd
@@ -0,0 +1,42 @@
+---
+title: "Hello, Quarto"
+format: html
+---
+
+```{r}
+#| label: load-packages
+#| include: false
+
+library(tidyverse)
+library(palmerpenguins)
+```
+
+## Meet Quarto
+
+Quarto enables you to weave together content and executable code into a finished document. To learn more about Quarto see <https://quarto.org>.
+
+## Meet the penguins
+
+![](lter_penguins.png){style="float:right;" fig-alt="Illustration of three species of Palmer Archipelago penguins: Chinstrap, Gentoo, and Adelie. Artwork by @allison_horst." width="401"}
+
+The `penguins` data from the [**palmerpenguins**](https://allisonhorst.github.io/palmerpenguins "palmerpenguins R package") package contains size measurements for `{r} nrow(penguins)` penguins from three species observed on three islands in the Palmer Archipelago, Antarctica.
+
+The plot below shows the relationship between flipper and bill lengths of these penguins.
+
+```{r}
+#| label: plot-penguins
+#| warning: false
+#| echo: false
+
+ggplot(penguins, 
+       aes(x = flipper_length_mm, y = bill_length_mm)) +
+  geom_point(aes(color = species, shape = species)) +
+  scale_color_manual(values = c("darkorange","purple","cyan4")) +
+  labs(
+    title = "Flipper and bill length",
+    subtitle = "Dimensions for penguins at Palmer Station LTER",
+    x = "Flipper length (mm)", y = "Bill length (mm)",
+    color = "Penguin species", shape = "Penguin species"
+  ) +
+  theme_minimal()
+```
diff --git a/docs/get-started/hello/_positron/r/lter_penguins.png b/docs/get-started/hello/_positron/r/lter_penguins.png
diff --git a/docs/get-started/hello/images/positron-editor-toolbar.png b/docs/get-started/hello/images/positron-editor-toolbar.png
diff --git a/docs/get-started/hello/images/positron-hello-python.png b/docs/get-started/hello/images/positron-hello-python.png
diff --git a/docs/get-started/hello/images/positron-hello-r.png b/docs/get-started/hello/images/positron-hello-r.png
diff --git a/docs/get-started/hello/images/positron-run-cell-python.png b/docs/get-started/hello/images/positron-run-cell-python.png
diff --git a/docs/get-started/hello/images/positron-run-cell-r.png b/docs/get-started/hello/images/positron-run-cell-r.png
diff --git a/docs/get-started/hello/positron.qmd b/docs/get-started/hello/positron.qmd
@@ -0,0 +1,234 @@
+---
+title: "Tutorial: Hello, Quarto"
+editor_options:
+  markdown:
+    wrap: sentence
+    canonical: true
+---
+
+{{< include ../_tool-chooser.md >}}
+
+:::{.callout-tip}
+
+# R or Python?
+
+You can work through this tutorial using R or Python code examples. 
+Select your preferred language:
+
+::: {.panel-tabset group="language"} 
+
+## R
+
+## Python
+
+:::
+
+:::
+
+## Overview
+
+Positron comes ready to work with Quarto out-of-the-box --- it includes both the Quarto command line interface and the Quarto VS Code extension. 
+
+In this tutorial, you'll learn how to use Positron with Quarto.
+You'll edit code and markdown in Positron and preview the rendered document in the Viewer pane as you work. 
+
+## Basic Workflow
+
+Here's what it might look like in Positron to edit and preview a Quarto document:
+
+::: {.panel-tabset group="language"} 
+
+## R
+
+![](images/positron-hello-r.png){.column-page-right .border fig-alt="Positron with a Quarto document titled \"Penguins, meet Quarto!\" open on the left side and the rendered version of the document on the right side." fig-align="center"}
+
+## Python
+
+![](images/positron-hello-python.png){.column-page-right .border fig-alt="Positron with a Quarto document titled \"Penguins, meet Quarto!\" open on the left side and the rendered version of the document on the right side." fig-align="center"}
+
+:::
+
+The Quarto document (`.qmd`) on the left contains a combination of markdown and executable code cells.
+It is *rendered* into the HTML version you see on the right.
+You could also choose to render it into other formats like PDF, MS Word, etc.
+
+This is the basic model for Quarto publishing---take a source document that combines code and narrative, and render it to a variety of output formats.
+
+## Setup
+
+If you would like to follow along with this tutorial in your own environment, follow the steps outlined below.
+
+::: {.panel-tabset group="language"} 
+
+## R
+
+1.  Be sure that you have installed the `tidyverse` and `palmerpenguins` packages:
+
+    ``` r
+    install.packages("tidyverse")
+    install.packages("palmerpenguins")
+    ```
+
+2.  Download the Quarto document (`.qmd`) below, open it in Positron.
+
+    ::: {.callout appearance="minimal"}
+    <i class="bi bi-download"></i> [Download hello.qmd](_positron/r/hello.qmd){download="hello.qmd"}
+    :::
+
+
+## Python
+
+1. Be sure that you have installed the `jupyter`, `plotnine` and `palmerpenguins` packages:
+
+    ``` bash 
+    pip install jupyter plotnine palmerpenguins
+    ```
+
+2.  Download the Quarto document (`.qmd`) below, open it in Positron.
+
+    ::: {.callout appearance="minimal"}
+    <i class="bi bi-download"></i> [Download hello.qmd](_positron/python/hello.qmd){download="hello.qmd"}
+    :::
+
+:::
+
+## Rendering
+
+We'll start out by rendering the example (`hello.qmd`).
+To render and preview the document, execute the **Quarto: Preview** command.
+You can alternatively use the keyboard shortcut {{< kbd mac=Command-Shift-K win=Ctrl+Shift+K linux=Ctrl+Shift+K >}}, or the **Preview** button (![](/docs/tools/images/vscode-preview-icon.svg){.light-content fig-alt="Preview icon"}![](/docs/tools/images/vscode-preview-icon-white.svg){.dark-content fig-alt="Preview icon"}) in the editor toolbar:
+
+![](images/positron-editor-toolbar.png){.border fig-alt="The top of the Positron code editor. The left side of the editor tab area includes a Preview button."}
+
+Quarto will render the document, and the rendered output will preview in the Viewer pane.
+This side-by-side preview works for HTML and PDF outputs.
+Other formats, like MS Word, will open externally.
+
+The preview will update whenever you rerun the **Quarto: Preview** command.
+If you prefer to automatically render whenever you save, you can check the **Render on Save** option on the editor toolbar.
+
+When rendering, Quarto generates a new file that contains selected text, code, and results from the `.qmd` file.
+The new file can be an [HTML](/docs/output-formats/all-formats.qmd), [PDF](/docs/output-formats/pdf-basics.qmd), [MS Word](/docs/output-formats/ms-word.qmd) document, [presentation](/docs/presentations/index.qmd), [website](/docs/websites/website-basics.qmd), [book](/docs/books/book-basics.qmd), [interactive document](/docs/interactive/index.qmd), or [other format](/docs/output-formats/all-formats.qmd).
+
+## Authoring
+
+Let's turn our attention to the contents of our Quarto document.
+The file contains three types of content: a YAML header, code cells, and markdown text.
+
+### YAML header
+
+At the top of the file are document level options specified using YAML demarcated by three dashes (`---`) on either end.
+
+``` yaml
+---
+title: "Hello, Quarto"
+format: html
+---
+```
+
+When rendered, the `title`, `"Hello, Quarto"`, will appear at the top of the rendered document with a larger font size than the rest of the document.
+The `format` field denotes that the output should be rendered to the `html` format.
+
+The basic syntax of YAML uses key-value pairs in the format `key: value`.
+Other YAML fields commonly found in headers of documents include metadata like `author`, `subtitle`, `date` as well as customization options like `theme`, `fontcolor`, `fig-width`, etc.
+You can find out about all available YAML fields for HTML documents [here](/docs/reference/formats/html.qmd).
+The available YAML fields vary based on document format, e.g., see [here](/docs/reference/formats/pdf.qmd) for YAML fields for PDF documents and [here](/docs/reference/formats/docx.qmd) for MS Word.
+
+### Code cells
+
+Code cells contain executable code to be run during render, with the output (and optionally the code) included in the rendered document.
+
+::: {.panel-tabset group="language"}
+
+## R
+
+Code cells are identified with `{r}` with (optional) chunk options, in YAML style, identified by `#|` at the beginning of the line.
+
+```` markdown
+```{{r}}
+#| label: load-packages
+#| include: false
+
+library(tidyverse)
+library(palmerpenguins)
+```
+````
+
+## Python 
+
+Code cells are identified with `{python}` with (optional) chunk options, in YAML style, identified by `#|` at the beginning of the line.
+
+```` markdown
+```{{python}}
+#| label: load-packages
+#| include: false
+
+from plotnine import *
+from palmerpenguins import load_penguins
+
+penguins = load_penguins()
+```
+````
+
+::: 
+
+
+In this case, the `label` of the code chunk is `load-packages`, and we set `include` to `false` to indicate that we don't want the chunk itself or any of its outputs in the rendered documents.
+There are a wide variety of code cell options you can apply to tailor your output.
+We'll delve into these options in the next tutorial.
+
+In addition to rendering the complete document to view the results of code cells, you can also run each code cell interactively.
+Use the command: **Quarto: Run Cell**, the keyboard shortcut ({{< kbd mac=Command-Shift-Enter windows=Control+Shift+Enter linux=Control+Shift+Enter >}}), or click Run Cell directly above the cell in the Editor. 
+
+::: {.panel-tabset group="language"}
+
+## R 
+
+![](images/positron-run-cell-r.png){fig-alt="A Positron session with `hello.qmd` open in the Editor. An orange box highlights the button 'Run Cell' above a code cell with the label `plot-penguins`. The Console shows an executed line of code ending in `theme_minimal()` and the Plots pane shows a scatterplot of penguin flipper and bill length." fig-align="center"}
+
+## Python
+
+![](images/positron-run-cell-python.png){fig-alt="A Positron session with `hello.qmd` open in the Editor. An orange box highlights the button 'Run Cell' above a code cell with the label `plot-penguins`. The Console shows an executed line of code ending in `theme_minimal()` and the Plots pane shows a scatterplot of penguin flipper and bill length." fig-align="center"}
+
+::: 
+
+Positron executes the code in the Console and displays the results.
+
+### Markdown text
+
+Narrative content is written using markdown. 
+For example, the following markdown text includes a section heading (`##`) and a link to the Quarto website:
+
+```markdown
+## Meet Quarto
+
+Quarto enables you to weave together content and executable code into a finished document. To learn more about Quarto see <https://quarto.org>.
+```
+
+Quarto supports markdown syntax for basic text formatting, tables, and images, as well as advanced features like citations, cross-references, and equations.
+
+## How it works
+
+:::{.panel-tabset group="language"}
+
+## R
+
+When you render a Quarto document, first [knitr](http://yihui.name/knitr/) executes all of the code cells and creates a new markdown (.md) document, which includes the code and its output.
+
+The markdown file generated is then processed by [pandoc](http://pandoc.org/), which creates the finished format.
+
+![](images/rstudio-qmd-how-it-works.png){.border fig-alt="Workflow diagram starting with a qmd file, then knitr, then md, then pandoc, then PDF, MS Word, or HTML."}
+
+## Python
+
+When you render a Quarto document, first [jupyter](https://jupyter.org) executes all of the code cells and creates a new markdown (.md) document, which includes the code and its output.
+
+The markdown file generated is then processed by [pandoc](http://pandoc.org/), which creates the finished format.
+
+![](images/qmd-how-it-works.png){.border fig-alt="Workflow diagram starting with a qmd file, then Jupyter, then md, then pandoc, then PDF, MS Word, or HTML."}
+
+:::
+
+
+
+{{< include _footer.md >}}
diff --git a/docs/get-started/images/positron-logo.svg b/docs/get-started/images/positron-logo.svg
diff --git a/docs/get-started/index.qmd b/docs/get-started/index.qmd
@@ -59,6 +59,9 @@ image: /images/hero_right.png
 
 ::: {.tool .g-col-lg-9 .g-col-12}
 
+<a href="hello/positron.html" role="button" class="btn btn-outline-light">
+![](images/positron-logo.svg){width="77" fig-alt="Positron logo."}Positron
+</a>
 
 <a href="hello/vscode.html" role="button" class="btn btn-outline-light">
 ![](images/vscode-logo.png){width="77" fig-alt="VS Code logo."}VS Code