Guide > Tools > Positron (#1654) (#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 <[email protected]>

Author: github-actions[bot]

_quarto.yml

@@ -194,15 +194,24 @@ website:
                         - docs/visual-editor/content.qmd
                         - docs/visual-editor/options.qmd
                         - docs/visual-editor/markdown.qmd
+                - section: "Positron"
+                  href: docs/tools/positron/index.qmd
+                  contents:
+                    - text: "Positron Basics"
+                      href: docs/tools/positron/index.qmd
+                    - text: "Visual Editor"
+                      href: docs/tools/positron/visual-editor.qmd
+                    - text: "Notebook Editor"
+                      href: docs/tools/positron/notebook.qmd
                 - section: "VS Code"
-                  href: docs/tools/vscode.qmd
+                  href: docs/tools/vscode/index.qmd
                   contents:
                     - text: "VS Code Basics"
-                      href: docs/tools/vscode.qmd
+                      href: docs/tools/vscode/index.qmd
                     - text: "Visual Editor"
-                      href: docs/visual-editor/vscode/index.qmd
+                      href: docs/tools/vscode/visual-editor.qmd
                     - text: "Notebook Editor"
-                      href: docs/tools/vscode-notebook.qmd
+                      href: docs/tools/vscode/notebook.qmd
                 - docs/tools/neovim.qmd
                 - docs/tools/text-editors.qmd
             - section: "Documents"

docs/computations/_jupyter-execute.md

@@ -6,7 +6,7 @@ quarto render notebook.ipynb --execute
 
 You can also specify this behavior within the notebook's YAML front matter:
 
-``` yaml
+```{.yaml filename="notebook.ipynb"}
 ---
 title: "My Notebook"
 execute: 

docs/computations/r.qmd

@@ -117,7 +117,7 @@ You can install the VS Code extension by searching for 'quarto' in the extension
 The VS Code extension includes a **Quarto: Preview** command that can be accessed via the Command Palette, the keyboard shortcut {{< kbd mac=Command-Shift-K win=Control-Shift-K linux=Control-Shift-K >}}, or a **Preview** button (![](/docs/tools/images/vscode-preview-icon.svg){fig-alt="Preview icon"}) in the editor. 
 After rendering, a preview is displayed in a pane within VS Code alongside your document.
 
-You can read more about using VS Code in [Tools: VS Code](/docs/tools/vscode.qmd).
+You can read more about using VS Code in [Tools: VS Code](/docs/tools/vscode/index.qmd).
 
 ## Emacs
 

docs/dashboards/index.qmd

@@ -26,7 +26,7 @@ Quarto Dashboards make it easy to create interactive dashboards using Python, R,
 
 -   Flexible and easy to specify row and column-based [Layouts](layout.qmd). Components are intelligently re-sized to fill the browser and adapted for display on mobile devices.
 
--   Author using any notebook editor ([JupyterLab](/docs/tools/jupyter-lab.qmd), etc.) or in plain text markdown with any text editor ([VS Code](/docs/tools/vscode.qmd), [RStudio](/docs/tools/rstudio.qmd), [Neovim](/docs/tools/neovim.qmd), etc.)
+-   Author using any notebook editor ([JupyterLab](/docs/tools/jupyter-lab.qmd), etc.) or in plain text markdown with any text editor ([VS Code](/docs/tools/vscode/index.qmd), [RStudio](/docs/tools/rstudio.qmd), [Neovim](/docs/tools/neovim.qmd), etc.)
 
 -   Dashboards can be deployed as static web pages (no special server required) or you can optionally integrate a backend [Shiny Server](/docs/dashboards/interactivity/shiny-python/index.qmd) for enhanced interactivity.
 

docs/get-started/authoring/vscode.qmd

@@ -12,4 +12,4 @@ editor_options:
 {{< include _text-editor.md >}}
 
 
-Additionally, if you are interested in seeing how to use Quarto from within `.ipynb` notebooks, check out the documentation on using the VS Code [Notebook Editor](/docs/tools/vscode.qmd#notebook-editor) with Quarto.
+Additionally, if you are interested in seeing how to use Quarto from within `.ipynb` notebooks, check out the documentation on using the VS Code [Notebook Editor](/docs/tools/vscode/notebook.qmd) with Quarto.

docs/get-started/hello/vscode.qmd

@@ -23,7 +23,7 @@ Before getting started, you should install the [Quarto VS Code Extension](https:
 You can install the Quarto extension from within the **Extensions** tab in VS Code, from the [Extension Marketplace](https://marketplace.visualstudio.com/items?itemName=quarto.quarto), the [Open VSX Registry](https://open-vsx.org/extension/quarto/quarto) or directly from a [VISX extension file](https://github.com/quarto-dev/quarto-vscode#visx-install).
 
 ::: callout-note
-This tutorial focuses on editing plain text Quarto `.qmd` files in VS Code. Depending on your preferences and the task at hand there are two other editing modes available for Quarto documents: the [Visual Editor](/docs/visual-editor/vscode/index.qmd) and the [Notebook Editor](/docs/tools/vscode-notebook.qmd). For the purposes of learning we recommend you work through this tutorial using the VS Code text editor, then after you've mastered the basics explore using the other editing modes.
+This tutorial focuses on editing plain text Quarto `.qmd` files in VS Code. Depending on your preferences and the task at hand there are two other editing modes available for Quarto documents: the [Visual Editor](/docs/tools/vscode/visual-editor.qmd) and the [Notebook Editor](/docs/tools/vscode/notebook.qmd). For the purposes of learning we recommend you work through this tutorial using the VS Code text editor, then after you've mastered the basics explore using the other editing modes.
 :::
 
 ### Basic Workflow
@@ -137,7 +137,7 @@ This is the basic workflow for authoring with Quarto.
 
 You do not need to save the file before rendering (as this happens automatically when you render).
 If you prefer, you can configure the Quarto extension to render whenever you save a document.
-See the documentation on [Render on Save](/docs/tools/vscode.qmd#render-on-save) for additional details.
+See the documentation on [Render on Save](/docs/tools/vscode/index.qmd#render-on-save) for additional details.
 
 ### Running Cells
 
@@ -239,6 +239,6 @@ If you prefer to use an external browser for preview (or have no preview trigger
 
 Additionally, you may wish to learn about the other editing modes for Quarto documents available within VS Code:
 
--  The [Visual Editor](/docs/visual-editor/vscode/index.qmd) for WYSIWYG editing of `.qmd` documents.
+-  The [Visual Editor](/docs/tools/vscode/visual-editor.qmd) for WYSIWYG editing of `.qmd` documents.
 
--  The [Notebook Editor](/docs/tools/vscode-notebook.qmd) for editing `.ipynb` notebooks.
+-  The [Notebook Editor](/docs/tools/vscode/notebook.qmd) for editing `.ipynb` notebooks.

docs/guide/guide.yml

@@ -43,7 +43,9 @@
     - text: RStudio IDE
       href: ../tools/rstudio.qmd
     - text: VS Code
-      href: ../tools/vscode.qmd
+      href: ../tools/vscode/index.qmd
+    - text: Positron
+      href: ../tools/positron/index.qmd
     - text: Neovim
       href: ../tools/neovim.qmd
     - text: Text Editors

docs/manuscripts/authoring/_overview.qmd

@@ -23,7 +23,7 @@ The syntax you'll learn will apply regardless of the tool you are using to edit
 
 ## Do you mostly use `.ipynb`?
 
-As a VS Code user, we recommend writing your article in a `.qmd` file. However, if you currently use VS Code primarily to work with `.ipynb` files, you may find the Jupyter Lab tutorial more applicable. Install the [Quarto extension for Jupyter Lab](#install-the-quarto-vs-code-extension), then pick up the Jupyter Lab tutorial at [Clone the Template Repository](jupyterlab.qmd#clone-repo). You might also like read about using [Quarto with VS Code's Notebook Editor](/docs/tools/vscode-notebook.qmd).
+As a VS Code user, we recommend writing your article in a `.qmd` file. However, if you currently use VS Code primarily to work with `.ipynb` files, you may find the Jupyter Lab tutorial more applicable. Install the [Quarto extension for Jupyter Lab](#install-the-quarto-vs-code-extension), then pick up the Jupyter Lab tutorial at [Clone the Template Repository](jupyterlab.qmd#clone-repo). You might also like read about using [Quarto with VS Code's Notebook Editor](/docs/tools/vscode/notebook.qmd).
 :::
 
 :::

docs/manuscripts/authoring/_visual-editor.qmd

@@ -29,7 +29,7 @@ To toggle between source and visual editor modes, use the Editor menu and select
 
 ![](images/source-visual-menu-vscode.png){fig-alt="Screenshot of the Editor menu in VS Code. The 'Edit in Visual Mode' item in the '...' menu is highlighted."}
 
-There are other ways to switch modes, read about them, and other features of the visual editor at [Visual Editing in VS Code](/docs/visual-editor/vscode/index.qmd).
+There are other ways to switch modes, read about them, and other features of the visual editor at [Visual Editing in VS Code](/docs/tools/vscode/visual-editor.qmd).
 :::
 
 You can switch between the source and visual editor at any time - the location of your cursor and undo/redo history is preserved.

docs/output-formats/_ssg-workflow.qmd

@@ -21,7 +21,7 @@ quarto preview
 
 This will automatically run `{{< meta ssg-preview >}}` on your behalf to bring up a local preview server. In addition, it will monitor the filesystem for changes to `.qmd` and `.ipynb` inputs and automatically re-render them to {{< meta ssg-name >}} compatible `.md` files when they change.
 
-Note that this also works for the integrated Render/Preview command within the [Quarto VS Code Extension](/docs/tools/vscode.qmd).
+Note that this also works for the integrated Render/Preview command within the [Quarto VS Code Extension](/docs/tools/vscode/index.qmd).
 
 ### Rendering