Guide > Tools > Positron #1654

cwickham · 2025-05-05T20:37:42Z

A first pass at Guide > Tools > Positron by making minor changes to Guide > Tools > VS Code:

Guide > Tools > Positron > Positron Basics
- VS code -> Positron (except in "VS Code Quarto Extension")
- Re-write Overview
- Preview panel -> preview in Viewer pane
- Custom Execution Directory section
- Alternate screenshots in:
  - Overview
  - Render and Preview
  - Code Cells
  - Contextual Assistance
Guide > Tools > Positron > Notebook Editor:
- VS code -> Positron
- Alternate screenshot in:
  - Render and Preview
Guide > Tools > Positron > Visual Editor:
- VS code -> Positron (except in "VS Code Quarto Extension")
- remove text "run in web browser". (Is "in Workbench" a better substitution?)
- No new screenshots

Most content is included from:

tools/_code-oss-editors.md
tools/_code-oss-notebook.md
tools/_code-oss-visual-editor.md

github-actions · 2025-05-05T20:43:50Z

🚀 Deployed on https://deploy-preview-1654.quarto.org

juliasilge

This is looking so great! 🙌 Thank you so much for working on this.

I noted some places where I don't think the screenshots can be re-used between Positron and VS Code, because of changes we've made to the UI. I think the other thing to consider is how to link to OpenVSX for the Positron pages.

Let me know if you have questions on any of that!

juliasilge · 2025-05-07T14:55:21Z

docs/tools/positron/index.qmd

+
+Positron bundles both the Quarto CLI and the VS Code Quarto extension so it comes ready to work with Quarto out-of-the-box.
+
+The [Quarto VS Code Extension](https://marketplace.visualstudio.com/items?itemName=quarto.quarto) provides the support for Quarto in Positron, including:


In Positron, we can't use the MS marketplace, so I think it would be better to link to OpenVSX here:
https://open-vsx.org/extension/quarto/quarto

juliasilge · 2025-05-07T14:55:47Z

docs/tools/positron/index.qmd

+
+The [Quarto VS Code Extension](https://marketplace.visualstudio.com/items?itemName=quarto.quarto) provides the support for Quarto in Positron, including:
+
+-   Integrated render and preview for Quarto documents.


Suggested change

- Integrated render and preview for Quarto documents.

- Integrated render and preview for Quarto documents

juliasilge · 2025-05-07T14:58:13Z

docs/tools/positron/index.qmd

+-   Live preview for LaTeX math as well as Mermaid and Graphviz diagrams
+
+The Quarto extension integrates directly with Positron's native R and Python features.
+For example, here the Quarto extension runs a Python cell in the active Python Console and shows contextual help for Python functions.


Positron has an integrated help pane also, so it is a little awkward to be showing the Quarto help pane. What do you think about highlighting something else here?

Yeah, I think that makes sense. I'll redo with an image preview.

juliasilge · 2025-05-07T14:58:52Z

docs/tools/positron/index.qmd

+
+![](/docs/tools/images/positron-python.png){.border .preview-image fig-alt="Screen shot of Positron editor with three vertical sections. The leftmost includes the file explorer, and quarto help. The second pane is the source code for a quarto file with python code, and the active Python Console. The third shows the Environment and Plots for the active console populated with the output of the code cells."}
+
+The Quarto extension also works well with other extensions bundled with Positron, like Jupyter extension, and those you might install separately, like the Julia extension.


Suggested change

The Quarto extension also works well with other extensions bundled with Positron, like Jupyter extension, and those you might install separately, like the Julia extension.

The Quarto extension works well with both other extensions bundled with Positron, like the Jupyter extension, as well as those you might install yourself separately, like the Julia extension.

juliasilge · 2025-05-07T15:01:39Z

docs/tools/_code-oss-editors.md

@@ -51,11 +29,11 @@ Note that on the Mac you should use `Cmd` rather than `Ctrl` as the prefix for a

 The **Quarto: Preview** command renders the default format of the currently active document. If you want to preview a different format, use the **Quarto: Preview Format** command:

-![](images/vscode-preview-format-menu.png){.border fig-alt="The top of the Visual Studio code editor. The editor title menu is expanded and the Preview Format command is available on the menu."}
+![](/docs/tools/images/vscode-preview-format-menu.png){.border fig-alt='The top of the {{< meta tool.name >}} editor. The editor title menu is expanded and the Preview Format command is available on the menu.'}


This screenshot is very clearly not Positron. Is it possible to have two versions here?

juliasilge · 2025-05-07T15:06:58Z

docs/tools/_code-oss-editors.md


 ## Code Snippets

 Code snippets are templates that make it easier to enter repeating code patterns (e.g. code blocks, callouts, divs, etc.). Execute the **Insert Snippet** command within a Quarto document to insert a markdown snippet:

-![](images/vscode-snippets.png){.border fig-alt="Quarto document with dropdown 'Select a snippet' dropdown, the first item (bold - insert bold text) is selected."}
+![](/docs/tools/images/vscode-snippets.png){.border fig-alt="Quarto document with dropdown 'Select a snippet' dropdown, the first item (bold - insert bold text) is selected."}


Can we have a Positron screenshot here?

juliasilge · 2025-05-07T15:07:05Z

docs/tools/_code-oss-editors.md

@@ -185,18 +188,18 @@ VSCode uses IntelliSense to suggest snippets or possible values for a specific f

 If you have a large document use the outline view for quick navigation between sections:

-![](images/vscode-outline.png){.border fig-alt="Quarto document with outline view shown in left-hand panel. The outline shows the section headers of the quarto documents."}
+![](/docs/tools/images/vscode-outline.png){.border fig-alt="Quarto document with outline view shown in left-hand panel. The outline shows the section headers of the quarto documents."}


Can we have a Positron screenshot here?

juliasilge · 2025-05-07T15:07:35Z

docs/tools/_code-oss-editors.md


 ## Code Snippets

 Code snippets are templates that make it easier to enter repeating code patterns (e.g. code blocks, callouts, divs, etc.). Execute the **Insert Snippet** command within a Quarto document to insert a markdown snippet:

-![](images/vscode-snippets.png){.border fig-alt="Quarto document with dropdown 'Select a snippet' dropdown, the first item (bold - insert bold text) is selected."}
+![](/docs/tools/images/vscode-snippets.png){.border fig-alt="Quarto document with dropdown 'Select a snippet' dropdown, the first item (bold - insert bold text) is selected."}

 ### IntelliSense


In this section, we should say "Positron" rather than "VSCode".

juliasilge · 2025-05-07T15:08:03Z

docs/tools/_code-oss-editors.md


 You can also use the **Go to Symbol in Editor** command or keyboard shortcut <kbd>Ctrl+Shift+O</kbd> for type-ahead navigation of the current document's outline.

 Use the **Go to File** command <kbd>Ctrl+P</kbd> to navigate to other files and the **Go to Symbol in Workspace** command <kbd>Ctrl+T</kbd> for type-ahead navigation to all headings in the workspace:

-![](images/vscode-workspace-symbols.png){.border fig-alt="Quarto document in VS Code with command palette open showing the files in the project with the entered term, 'margin'."}
+![](/docs/tools/images/vscode-workspace-symbols.png){.border fig-alt='Quarto document in {{< meta tool.name >}} with command palette open showing the files in the project with the entered term, \'margin\'.'}


Can we have a Positron screenshot here?

juliasilge · 2025-05-07T15:11:29Z

docs/tools/_code-oss-visual-editor.md

---
-title: "Visual Editing in VS Code"
---
-
 ## Overview

 The [Quarto VS Code Extension](https://marketplace.visualstudio.com/items?itemName=quarto.quarto) includes a visual markdown editor that supports all of Quarto's markdown syntax including tables, citations, cross-references, footnotes, divs/spans, definition lists, attributes, raw HTML/TeX, and more:


For the Positron version of this page (or both!) we shouldn't link to the MS marketplace.

I do think this page could use some updates to be more accurate for Positron. For example, you can't switch between source and visual mode from the editor menu but you can from the new bar.

The screenshots that show the tab bar should be updated, since we have made UI changes there; the screenshots of just the command palette are OK. 👍

For example, you can't switch between source and visual mode from the editor menu but you can from the new bar.

I added the new bar. I think you can still switch from the editor menu, at least I generated a screenshot in Positron that shows it 🤷🏻‍♀️

The screenshots that show the tab bar should be updated, since we have made UI changes there; the screenshots of just the command palette are OK

Updated any that showed any Positron UI elements.

github-actions · 2025-05-12T21:52:03Z

🚀 Deployed on https://deploy-preview-1654.quarto.org

github-actions · 2025-05-12T21:58:46Z

🚀 Deployed on https://deploy-preview-1654.quarto.org

github-actions · 2025-05-13T18:31:34Z

🚀 Deployed on https://deploy-preview-1654.quarto.org

github-actions · 2025-05-13T21:57:20Z

🚀 Deployed on https://deploy-preview-1654.quarto.org

cwickham · 2025-05-13T22:00:34Z

@juliasilge The main "Guide > Tools > Positron" page now has exclusively Positron screenshots (including dark ones for dark mode) 🚀 Would you like to take another quick look?

juliasilge

This is looking great! 🙌

We are still making some changes to the UI (especially that new toolbar) so I think it would be a good idea to set aside some time in July or so to update the screenshots with the first non-beta release of Positron. Let me know if you have any questions on that, including on timing!

juliasilge · 2025-05-19T13:23:34Z

docs/tools/_code-oss-editors.md

+
+If you have multiple declared formats you can render all of them. You can also selectively render any of the declared formats or other standard formats like PDF and MS Word.
+
+## Render on Save


It would be good to highlight the toolbar checkbox in this section as well.

github-actions · 2025-05-29T21:31:21Z

📝 Preview Deployment

🔍 Full site preview: https://deploy-preview-1654.quarto.org

🔄 Modified Documents

* Add Positron notebook page * Add Positron Visual Editor * Fix file path * Add Positron landing * Add to Guide * Add screenshots * Re-organize * Fix explicit tool names * Use image preview instead of contextual help * Marketplace -> VSX * Use correct classes and images * Propogate change to later section * Show better Preview button in dark mode * More Positron specific screenshots + dark * More Positron specific screenshots * Add mention of toolbar Render on Save checkbox (cherry picked from commit c71396c)

github-actions · 2025-05-29T22:09:50Z

Successfully created backport PR for prerelease:

[Sync to prerelease] Guide > Tools > Positron #1676

* Add Positron notebook page * Add Positron Visual Editor * Fix file path * Add Positron landing * Add to Guide * Add screenshots * Re-organize * Fix explicit tool names * Use image preview instead of contextual help * Marketplace -> VSX * Use correct classes and images * Propogate change to later section * Show better Preview button in dark mode * More Positron specific screenshots + dark * More Positron specific screenshots * Add mention of toolbar Render on Save checkbox (cherry picked from commit c71396c) Co-authored-by: Charlotte Wickham <charlotte.wickham@posit.co>

cwickham added 8 commits May 2, 2025 14:00

Add Positron notebook page

f5b44c2

Add Positron Visual Editor

75a0d61

Fix file path

029a2e4

Add Positron landing

e5ce3e6

Add to Guide

934079d

Add screenshots

17b0553

Re-organize

fb1d963

Fix explicit tool names

8cd203d

github-actions bot temporarily deployed to pull request May 5, 2025 20:43 Inactive

cwickham changed the title ~~WIP: Guide > Tools > Positron~~ Guide > Tools > Positron May 5, 2025

cwickham marked this pull request as ready for review May 5, 2025 21:03

cwickham requested a review from juliasilge May 6, 2025 16:11

juliasilge suggested changes May 7, 2025

View reviewed changes

cwickham added 3 commits May 12, 2025 14:44

Use image preview instead of contextual help

c6857fd

Marketplace -> VSX

fbf967f

Merge branch 'main' into positron

a291177

github-actions bot temporarily deployed to pull request May 12, 2025 21:52 Inactive

Use correct classes and images

ad8238f

github-actions bot temporarily deployed to pull request May 12, 2025 21:58 Inactive

cwickham added 3 commits May 12, 2025 15:02

Propogate change to later section

1cdb2e5

Show better Preview button in dark mode

ddfaa91

More Positron specific screenshots + dark

25a1dc3

github-actions bot temporarily deployed to pull request May 13, 2025 18:31 Inactive

More Positron specific screenshots

f2f929a

github-actions bot temporarily deployed to pull request May 13, 2025 21:57 Inactive

juliasilge approved these changes May 19, 2025

View reviewed changes

Add mention of toolbar Render on Save checkbox

01e8c9e

github-actions bot temporarily deployed to pull request May 29, 2025 21:31 Inactive

cwickham merged commit c71396c into main May 29, 2025
4 checks passed

cwickham deleted the positron branch May 29, 2025 22:09

github-actions bot mentioned this pull request May 29, 2025

[Sync to prerelease] Guide > Tools > Positron #1676

Merged


		Positron bundles both the Quarto CLI and the VS Code Quarto extension so it comes ready to work with Quarto out-of-the-box.

		The [Quarto VS Code Extension](https://marketplace.visualstudio.com/items?itemName=quarto.quarto) provides the support for Quarto in Positron, including:


		The [Quarto VS Code Extension](https://marketplace.visualstudio.com/items?itemName=quarto.quarto) provides the support for Quarto in Positron, including:

		- Integrated render and preview for Quarto documents.


		![](/docs/tools/images/positron-python.png){.border .preview-image fig-alt="Screen shot of Positron editor with three vertical sections. The leftmost includes the file explorer, and quarto help. The second pane is the source code for a quarto file with python code, and the active Python Console. The third shows the Environment and Plots for the active console populated with the output of the code cells."}

		The Quarto extension also works well with other extensions bundled with Positron, like Jupyter extension, and those you might install separately, like the Julia extension.

	The Quarto extension also works well with other extensions bundled with Positron, like Jupyter extension, and those you might install separately, like the Julia extension.
	The Quarto extension works well with both other extensions bundled with Positron, like the Jupyter extension, as well as those you might install yourself separately, like the Julia extension.


		If you have multiple declared formats you can render all of them. You can also selectively render any of the declared formats or other standard formats like PDF and MS Word.

		## Render on Save

Guide > Tools > Positron #1654

Guide > Tools > Positron #1654

Uh oh!

Conversation

cwickham commented May 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented May 5, 2025

Uh oh!

juliasilge left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented May 12, 2025

Uh oh!

github-actions bot commented May 12, 2025

Uh oh!

github-actions bot commented May 13, 2025

Uh oh!

github-actions bot commented May 13, 2025

Uh oh!

cwickham commented May 13, 2025

Uh oh!

juliasilge left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented May 29, 2025

📝 Preview Deployment

🔄 Modified Documents

Uh oh!

Uh oh!

github-actions bot commented May 29, 2025

Uh oh!

Uh oh!

cwickham commented May 5, 2025 •

edited

Loading

juliasilge left a comment •

edited

Loading