Skip to content

Get Started > Positron #1692

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 22 commits into
base: main
Choose a base branch
from
Open

Get Started > Positron #1692

wants to merge 22 commits into from

Conversation

cwickham
Copy link
Collaborator

@cwickham cwickham commented Jun 11, 2025

Audience

For Positron users, assume these are people who work with data (as opposed to VS Code flow, where readers might be software developers, or more scientific computing types).

Assume no prior knowledge of similar systems, e.g. RMarkdown.

Summary

This is mostly a reuse and blend of the RStudio and VS Code flows with the following big modifications:

  • R and Python options with the same document content
  • Positron-specific screenshots where appropriate
  • computations/positron.qmd - it felt like there was too much material in this one so I trimmed heavily. Added a "Cell Workflow" section.

Thoughts and questions

  • Can we add some CSS to minimize the appearance of the tabsets? I.e. I want to keep the tab headers (although maybe they could move to right), but would like to have tab content inline with other content (i.e. not indented). Done

  • The example doc doesn't show computational output in the initial screenshot. Should we re-write to move a code cell earlier? A bit more like: https://quarto.org/index.html#python-tab. Yes, it removes dependency on an external image, and helps cement the purpose of computational cells.

  • It might be nice to include more advanced features in the example doc like a cross-reference, or a caption. Now includes cross-reference.

  • Would Python users be put off by using plotnine as opposed to something like matplotlib? (I personally like that the two example documents look identical despite the language used to create them). Verdict is, no, this is fine.

  • Currently, this is mostly a "look at this tutorial". Should it involve more doing? I.e. "Edit the heading and re-render". No problems with first page being mostly "look at this". Next steps, could be more "do this".

@github-actions github-actions bot temporarily deployed to pull request June 11, 2025 21:42 Inactive
Copy link
Contributor

@jthomasmock
Copy link
Contributor

Howdy @cwickham -- would this be OK to rollout by the start of July? Any review of revisions we can help with?

@github-actions github-actions bot temporarily deployed to pull request June 24, 2025 16:16 Inactive
Copy link
Contributor

@github-actions github-actions bot temporarily deployed to pull request June 24, 2025 22:49 Inactive
Copy link
Contributor

@github-actions github-actions bot temporarily deployed to pull request June 27, 2025 23:02 Inactive
@github-actions github-actions bot temporarily deployed to pull request June 30, 2025 18:03 Inactive
@github-actions github-actions bot temporarily deployed to pull request June 30, 2025 20:14 Inactive
@github-actions github-actions bot temporarily deployed to pull request June 30, 2025 20:23 Inactive
@cwickham
Copy link
Collaborator Author

I've opened quarto-dev/quarto-cli#13010 for a future where we can get people up and running with all the documents and packages with a single (or sequence) of Positron commands.

@cwickham cwickham marked this pull request as ready for review June 30, 2025 20:35
Copy link
Collaborator

@juliasilge juliasilge left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is looking so great! 🎉

I really like the tabset treatment on these pages and think the new minimal CSS treatment is really nice in this context. I am a bit worried about the first time there is one on the page with the very minimal tabset treated as a switcher; it looks so understated that I myself was a bit confused about what it was supposed to me. It might just be me, though; maybe we can show this to a few more people to see if it's clear to them what to do.

Comment on lines +8 to +14
::: {.panel-tabset group="language"}

## R

## Python

:::
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have kind of mixed feelings about having a tabset without content in it set up to use as a chooser, and worry that it is not a typical enough website gesture for folks to understand. Maybe we can get another set of eyes on whether this makes sense? Would it be better if there was some content in it?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed. I'm guessing this couldn't be a radio button, as the selection then carries through to other tabsets. Could this particular tabset be styled differently with CSS to make it look like a radio button or like boxes on top of the page for tool selection? Alternatively, adding some descriptor text would resolve the issue too. Maybe something like "If you primarily code in R, select this tab to see code examples in R. You can always switch over to Python whenever you like throughout the guide."


* The [Visual Editor](/docs/tools/positron/visual-editor.qmd) allows you to create and edit `.qmd` documents using a WYSIWYG interface. This is particularly useful for users who prefer a more visual approach to document creation without needing to write markdown directly.

* The [Notebook Editor](/docs/tools/positron/notebook.qmd) for editing `.ipynb` notebooks. This editor is designed for users who are accustomed to working with Jupyter notebooks and want to leverage the features of Quarto within that environment.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* The [Notebook Editor](/docs/tools/positron/notebook.qmd) for editing `.ipynb` notebooks. This editor is designed for users who are accustomed to working with Jupyter notebooks and want to leverage the features of Quarto within that environment.
* The [Notebook Editor](/docs/tools/positron/notebook.qmd) is for editing `.ipynb` notebooks. This editor is designed for users who are accustomed to working with Jupyter notebooks and want to leverage the features of Quarto within that environment.

Comment on lines +28 to +45
::: {.grid .step .column-page-right}
::: {.g-col-lg-3 .g-col-12}
## Using Positron?

#### Jump straight in {.fw-light}

:::

::: {.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."} Get Started with Quarto in Positron
</a>



:::

:::
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I'd lean toward not calling out Positron in this way on this page, ahead of even downloading Quarto itself. I tend to think that putting it first in the icons a bit lower is already enough emphasis.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree.


## 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"}
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When I view these in the deploy preview, the screenshots go past the main content area out on the left, which is different from the same content on the other IDE pages and does not interact well with the TOC. Is it possible for us to treat these screenshots more similarly to the screenshots of other IDEs?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Related to screenshots, can you say a bit more about using dark mode for all of these? I think I would want to advocate for the default Positron theme, unless there is a particular reason for going with dark mode here.


:::

{{< include _footer.md >}}
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the deploy preview, the links from this include go to empty pages. Do those need to be updated?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These were broken on quarto.org too 😬. Fixed now.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the yellow background on the screenshots in this PR intentional? I think I would prefer to see the more typical white.

:::


{{< include _footer.md >}}
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The links from this include seem to go to empty pages.

Copy link
Collaborator

@mine-cetinkaya-rundel mine-cetinkaya-rundel left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks great, made some suggestions throughout.

A couple of more comments:

  • Switching between R and Python tabs make the page jump, but there may be nothing to be done about that.

  • I couldn't make an inline suggestions for these since they weren't edited during this PR:

    • under ## Citations in _text-editor.md: "To cite other works within a Quarto document. First create a bibliography" = "To cite other works within a Quarto document, first create a bibliography"

    • "Cross References" = "Cross-References" in _text-editor.md.

Comment on lines +8 to +14
::: {.panel-tabset group="language"}

## R

## Python

:::
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed. I'm guessing this couldn't be a radio button, as the selection then carries through to other tabsets. Could this particular tabset be styled differently with CSS to make it look like a radio button or like boxes on top of the page for tool selection? Alternatively, adding some descriptor text would resolve the issue too. Maybe something like "If you primarily code in R, select this tab to see code examples in R. You can always switch over to Python whenever you like throughout the guide."

Quarto is an open-source scientific and technical publishing system that weaves together code and narrative to produce high-quality documents, presentations, websites, and more.
In this tutorial, you'll learn how to use Positron with Quarto.

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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be nice to link to the landing page for the VS Code extension (maybe it would get it some stars too?). This is the right place for that? https://open-vsx.org/extension/quarto/quarto.


- Positron's full R and Python support for code that is inside a Quarto document, including interactive execution of code in the Console, code completion, help, and diagnostics.

Here's an example Quarto document, `hello.qmd`, open in Positron, demonstrating the seamless side-by-side editing and preview experience:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Here's an example Quarto document, `hello.qmd`, open in Positron, demonstrating the seamless side-by-side editing and preview experience:
Here's a sample Quarto document, `hello.qmd`, open in Positron, demonstrating the seamless side-by-side editing and preview experience:

install.packages("palmerpenguins")
```

2. Download the Quarto document (`.qmd`) below, open it in Positron.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
2. Download the Quarto document (`.qmd`) below, open it in Positron.
2. Download the Quarto document (`hello.qmd`) below and open it in Positron.

pip install jupyter plotnine
```

2. Download the Quarto document (`.qmd`) below, open it in Positron.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
2. Download the Quarto document (`.qmd`) below, open it in Positron.
2. Download the Quarto document (`hello.qmd`) below and open it in Positron.


Code cells using the `` ```{language} `` syntax are sometimes called *executable* code cells because they will be executed by the computational engine (e.g. `knitr` or `jupyter`).

If you want to show code without it being processed by the computational engine use a code block:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If you want to show code without it being processed by the computational engine use a code block:
If you want to show code without it being processed by the computational engine, use a code block:


:::

You can read more, and see some syntax alternatives, at [Markdown Basics: Source Code](/docs/authoring/markdown-basics.qmd#source-code)
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
You can read more, and see some syntax alternatives, at [Markdown Basics: Source Code](/docs/authoring/markdown-basics.qmd#source-code)
You can read more and see some syntax alternatives at [Markdown Basics: Source Code](/docs/authoring/markdown-basics.qmd#source-code).


## R

To include executable expressions within markdown text, enclose the expression in `` `{r} ` ``^[Quarto also supports the Knitr syntax `` `r ` ``, read more in [Inline Code](/docs/computations/inline-code.qmd)].
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
To include executable expressions within markdown text, enclose the expression in `` `{r} ` ``^[Quarto also supports the Knitr syntax `` `r ` ``, read more in [Inline Code](/docs/computations/inline-code.qmd)].
To include executable expressions within markdown text, enclose the expression in `` `{r} ` ``^[Quarto also supports the Knitr syntax `` `r ` ``, read more in [Inline Code](/docs/computations/inline-code.qmd).].

If the expression you want to inline is more complex, involving many functions or a pipeline, we recommend including it in a code cell (with `echo: false`) and assigning the result to an object.
Then, you can call that object in your inline code.

For additional details on inline code expressions, visit the [Inline Code](/docs/computations/inline-code.qmd) page.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
For additional details on inline code expressions, visit the [Inline Code](/docs/computations/inline-code.qmd) page.
For additional details on inline code expressions, visit the [Inline Code](/docs/computations/inline-code.qmd) documentation.

@@ -0,0 +1,14 @@
When you preview a document with the **Quarto: Preview** command, the Preview button in the toolbar, or the keyboard shortcut {{< kbd mac=Command-Shift-K win=Ctrl+Shift+K linux=Ctrl+Shift+K >}}
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
When you preview a document with the **Quarto: Preview** command, the Preview button in the toolbar, or the keyboard shortcut {{< kbd mac=Command-Shift-K win=Ctrl+Shift+K linux=Ctrl+Shift+K >}}
When you preview a document with the **Quarto: Preview** command, the Preview button in the toolbar, or the keyboard shortcut {{< kbd mac=Command-Shift-K win=Ctrl+Shift+K linux=Ctrl+Shift+K >}},

@github-actions github-actions bot temporarily deployed to pull request July 1, 2025 16:56 Inactive
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants