Add more docs around migration from RStudio

.github/styles/config/vocabularies/posit-docs/accept.txt

@@ -40,3 +40,5 @@ Action Bar
 Action Bars
 Top Action Bar
 Jupyter Notebooks
+Air
+R

_quarto.yml

@@ -82,9 +82,13 @@ website:
           href: migrate-vscode.qmd
         - section: "Migrating from RStudio"
           contents:
-          - rstudio-keybindings.qmd
+          - migrate-rstudio-overview.qmd
+          - migrate-rstudio-keybindings.qmd
+          - migrate-rstudio-workspace.qmd
           - rstudio-rproj-file.qmd
-          - r-snippets.qmd
+          - migrate-rstudio-code.qmd
+          - migrate-rstudio-navigation.qmd
+          - migrate-rstudio-settings-and-extensions.qmd
     - title: "Help"
       style: "docked"
       contents:

faqs.qmd

@@ -36,5 +36,5 @@ title: "Frequently Asked Questions"
 
 ### I'm coming from RStudio, and Positron's keybindings are too different
 
-* Check out the [RStudio Keymap](keyboard-shortcuts.qmd#rstudio-keymap) section of our documentation.
+* Check out the [RStudio Keymap](migrate-rstudio-keybindings.qmd) section of our documentation.
 * To opt in to these RStudio-like keybindings, enable the [`workbench.keybindings.rstudioKeybindings` setting](positron://settings/workbench.keybindings.rstudioKeybindings).

keyboard-shortcuts.qmd

@@ -8,9 +8,9 @@ Positron's keyboard shortcuts, with a few exceptions, are a superset of the keyb
 
 | Shortcut | Description |
 | -------- | ----------- |
-| <kbd>Cmd/Ctrl</kbd>+<kbd>Enter</kbd> | Run the selected code in the editor; if no code is selected, run the current statement | 
-| <kbd>Cmd/Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>0</kbd> | Restart the interpreter currently open in the Console | 
-| <kbd>Cmd/Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Enter</kbd> | Run the file open in the editor (using e.g. `source()` or `%run`) | 
+| <kbd>Cmd/Ctrl</kbd>+<kbd>Enter</kbd> | Run the selected code in the editor; if no code is selected, run the current statement |
+| <kbd>Cmd/Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>0</kbd> | Restart the interpreter currently open in the Console |
+| <kbd>Cmd/Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Enter</kbd> | Run the file open in the editor (using e.g. `source()` or `%run`) |
 | <kbd>F1</kbd> | Show contextual help for the topic under the cursor |
 | <kbd>Cmd/Ctrl</kbd>+<kbd>K</kbd>, <kbd>Cmd/Ctrl</kbd>+<kbd>R</kbd> | Show contextual help for the topic under the cursor (alternate binding) |
 | <kbd>Cmd/Ctrl</kbd>+<kbd>K</kbd>, <kbd>F</kbd> | Focus the Console |
@@ -21,21 +21,23 @@ Positron's keyboard shortcuts, with a few exceptions, are a superset of the keyb
 
 | Shortcut | Description |
 | -------- | ----------- |
-| <kbd>Cmd/Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>M</kbd> | Insert the pipe operator (<code>&#124;></code> or `%>%`) | 
+| <kbd>Cmd/Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>M</kbd> | Insert the pipe operator (<code>&#124;></code> or `%>%`, depending on [`positron.r.pipe`](positron://settings/positron.r.pipe) |
 | <kbd>Alt</kbd>+<kbd>-</kbd> | Insert the assignment operator (`<-`) |
-| <kbd>Cmd/Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>L</kbd> | Load the current R package, if any | 
-| <kbd>Cmd/Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>B</kbd> | Build and install the current R package, if any | 
-| <kbd>Cmd/Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>T</kbd> | Test the current R package, if any | 
-| <kbd>Cmd/Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>E</kbd> | Check the current R package, if any | 
-| <kbd>Cmd/Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>D</kbd> | Document the current R package, if any | 
+| <kbd>Ctrl/Cmd</kbd>+<kbd>Shift</kbd>+<kbd>Enter</kbd> | `source()` the current R script |
+| <kbd>Ctrl/Cmd</kbd>+<kbd>K</kbd> <kbd>H</kbd> | Insert section |
+| <kbd>Cmd/Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>L</kbd> | Load the current R package, if any, with `devtools::load_all()` |
+| <kbd>Cmd/Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>B</kbd> | Build and install the current R package, if any |
+| <kbd>Cmd/Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>T</kbd> | Test the current R package, if any |
+| <kbd>Cmd/Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>E</kbd> | Check the current R package, if any |
+| <kbd>Cmd/Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>D</kbd> | Document the current R package, if any |
 
 ## RStudio keybindings
 
-If you'd prefer to use RStudio keybindings, see [our instructions](rstudio-keybindings.qmd) on how to enable them for Positron.
+If you'd prefer to use RStudio keybindings, see [our instructions](migrate-rstudio-keybindings.qmd) on how to enable them for Positron.
 
 ## Custom shortcuts
 
-Because Positron is built on top of VS Code, you can use [its infrastructure for defining custom keybindings](https://code.visualstudio.com/docs/getstarted/keybindings). You can use this infrastructure with any Positron-specific commands, such as `workbench.action.executeCode.console` or `workbench.action.executeCode.silently`. 
+Because Positron is built on top of VS Code, you can use [its infrastructure for defining custom keybindings](https://code.visualstudio.com/docs/getstarted/keybindings). You can use this infrastructure with any Positron-specific commands, such as `workbench.action.executeCode.console` or `workbench.action.executeCode.silently`.
 
 As a specific example, you could add the following to your user `keybindings.json` (access this file from the Command Palette with *Open Keyboard Shortcuts (JSON)*) to make a keyboard shortcut to create a reprex from your current selection:
 
@@ -52,6 +54,15 @@ As a specific example, you could add the following to your user `keybindings.jso
 }
 ```
 
+## Troubleshooting and customization
+
+If you are puzzled by the behaviour of a keyboard shortcut, here are two issues to consider:
+
+* Context: many keyboard shortcuts, including those above, are only enabled in certain contexts, such as when editing code or when working in an R package. Consider if you might be invoking the shortcut in an unexpected and unsupported context.
+* Conflicts: a keyboard shortcut can have multiple associations across different situations or extensions. When a shortcut is associated with more than one command, a priority system determines which command wins and the result might not be what you expect.
+
+The command 'Preferences: Open Keyboard Shortcuts' opens an interface that is a great way to investigate keyboard shortcut mysteries.
+
 Be aware that Positron's integrated terminal can [intercept some keyboard shortcuts](https://code.visualstudio.com/docs/terminal/advanced#_keyboard-shortcuts-and-the-shell). You can set up a keybinding to skip the shell by specifying its command in the [`terminal.integrated.commandsToSkipShell` setting](positron://settings/terminal.integrated.commandsToSkipShell), either via the settings UI or by editing `settings.json`:
 
 ```json
@@ -61,4 +72,4 @@ Be aware that Positron's integrated terminal can [intercept some keyboard shortc
         "workbench.action.positronConsole.focusConsole"
     ]
 }
-```
+```

r-snippets.qmd → migrate-rstudio-code.qmd

@@ -1,7 +1,79 @@
 ---
-title: "Snippets for R"
+title: "Writing R code"
+aliases:
+  - r-snippets.qmd
 ---
 
+Writing R code in Positron should feel quite familiar to RStudio users.
+However two aspects of the workflow might feel a bit different:
+
+* Formatting via Air
+* Snippets, both built-in and custom
+
+## Formatting R code with Air
+
+Positron can format R code with [Air](https://posit-dev.github.io/air/), a new R formatter whose creation was largely motivated by Positron.
+
+A formatter takes charge of the layout of your R code, which refers to whitespace, newlines, indentation, and the like.
+The goal is to enforce a set of style conventions that enhance readability and robustness.
+Air shares properties with other modern formatters and linters, such as Black and Ruff for Python:
+
+* It's highly opinionated and offers relatively few options for customization.
+* It's written in Rust, which makes it extremely fast.
+
+### How does Positron get Air?
+
+Air is fundamentally a command line tool, but fortunately the Air CLI ships with Positron.
+Most Positron users do not need to do anything intentional to install Air or to keep it up-to-date.
+
+Under the hood, Air is packaged in a VS Code extension and that extension is one of the so-called [bootstrapped extensions](extensions.qmd) that come with a fresh Positron installation.
+The Air extension is published on [Open VSX](https://open-vsx.org/extension/posit/air-vscode), the marketplace used by IDEs like Positron and Cursor, and also on the [Visual Studio Code Marketplace](https://marketplace.visualstudio.com/items?itemName=Posit.air-vscode), which serves only VS Code.
+
+### When and how does Air run?
+
+There are various explicit and implicit gestures to run Air over your code:
+
+* "Format on save": formats R code every time you save a file. This is a lifestyle you must opt in to, but it is our strong recommendation that you do so. Below we give details on how to set this up.
+* Formatting commands: These are explicit gestures to format specific bits of code.
+  - *Format Selection*
+  - *Format Document*
+  - *Format Cell*
+  - *Air: Format Workspace Folder*
+
+  These are all available in the command palette.
+
+R code receives some formatting as you type, but these rules are based on regular expressions, which fundamentally limits their capability.
+A second formatting pass with Air, when you save the file or intentionally format it, produces a much better result, since Air works off of an actual syntax tree.
+
+### Opt in to "Format on save"
+
+The easiest way to get our recommended set up is to run [`usethis::use_air()`](https://usethis.r-lib.org/dev/reference/use_air.html) (note that this currently requires the development version of usethis).
+`use_air()` configures "Format on save" in the current workspace by modifying (or creating, if necessary) the `.vscode/settings.json` file.
+It also creates an `air.toml` file.
+
+VS Code and Positron let you customize settings at the user level and at the workspace level (i.e. for just the current project you are working on).
+We think "Format on save" makes the most sense to configure at the workspace level:
+
+* Workspace settings are recorded inside the workspace at `.vscode/settings.json`, allowing them to be tracked in version control. This means that all collaborators get those settings automatically when they check out the project, enforcing a common formatting style.
+* User level settings apply to any workspaces that you open. This sounds nice in theory, but you might not want automatic Air formatting in older projects or in projects that you don't own. If you opt in at the user level, you'll have to turn Air off somehow in these projects or risk creating a huge number of formatting diffs, when that's probably not your intent.
+
+Here is what `.vscode/settings.json` might look like for someone who wants their R code formatted on save, in both R scripts and Quarto documents:
+
+```json
+{
+    "[quarto]": {
+        "editor.formatOnSave": true
+    },
+    "[r]": {
+        "editor.formatOnSave": true
+    }
+}
+```
+
+To learn more about using Air, read its documentation for [Positron and VS Code](https://posit-dev.github.io/air/editor-vscode.html).
+
+## R snippets
+
 Code snippets let you insert ready-made templates for common coding patterns.
 For example, `for` is a reserved word in R that is used to create a loop.
 In actual usage, `for` is always part of a larger construct:
@@ -24,7 +96,7 @@ Documentation on snippets in:
 * [RStudio](https://docs.posit.co/ide/user/ide/guide/productivity/snippets.html)
 * [VS Code](https://code.visualstudio.com/docs/editing/userdefinedsnippets)
 
-## Default and custom snippets in RStudio
+### Default and custom snippets in RStudio
 
 RStudio ships with a default set of snippets.
 For our purposes, it's useful to break them into two broad classes:
@@ -37,7 +109,7 @@ Under the hood, this initializes a user-level snippet file that is pre-populated
 You can then apply your desired changes, such as adding or deleting snippets.
 Going forward, this user-level file powers all of your RStudio snippets, i.e. there is no combining of built-in and user-level snippets.
 
-## Default and custom snippets in Positron
+### Default and custom snippets in Positron
 
 The completion experience in Positron arises from two components working together:
 
@@ -49,14 +121,14 @@ The completion experience in Positron arises from two components working togethe
 
 This division of labor means that the completion and snippet responsibilities are a bit different in Positron than in RStudio.
 
-### Reserved words
+#### Reserved words
 
 In Positron, the completion items related to R's reserved words are built into ark.
 Each reserved word can be completed on its own and, in some cases, as part of a larger snippet.
 
 ![Completion list with rectangles highlighting two entries for the `function` reserved word, one as a bare keyword completion and another as a snippet](images/snippets-keyword-with-two-items.png){width=700}
 
-### Everything else
+#### Everything else
 
 If you want snippets beyond those provided for R's reserved words, you'll need to configure that for yourself.
 Press <kbd>Cmd/Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> to open the command palette and type *Snippets: Configure Snippets*.

migrate-rstudio-keybindings.qmd

@@ -0,0 +1,42 @@
+---
+title: "RStudio Keybindings"
+aliases:
+  - rstudio-keybindings.html
+---
+
+<!-- vale Posit.Contractions = NO -->
+
+Keyboard shortcuts are the most efficient way to accomplish tasks that come up frequently in your coding workflow.
+As you migrate from RStudio to Positron, maintaining your productivity means working with—not against—your muscle memory.
+
+Many familiar shortcuts will work immediately, because they are built-in to Positron and its integrated R support.
+These are documented with [Positron's keyboard shortcuts](keyboard-shortcuts.qmd).
+That is also where you can learn how to customize shortcuts.
+
+## RStudio keybindings in Positron
+
+A large set of RStudio keybindings can be enabled with the [`workbench.keybindings.rstudioKeybindings` setting](positron://settings/workbench.keybindings.rstudioKeybindings).
+Restart Positron after changing this setting.
+
+| Shortcut | Description |
+| -------- | ----------- |
+| <kbd>Ctrl</kbd>+<kbd>1</kbd>  |  Focus Source |
+| <kbd>Ctrl</kbd>+<kbd>2</kbd>  |  Focus Console |
+| <kbd>Cmd/Ctrl</kbd>+<kbd>.</kbd>  |  Go to Function/Symbol |
+| <kbd>Cmd/Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>C</kbd> |  Comment/Uncomment a line |
+| <kbd>Cmd/Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>N</kbd> |  Create a new R file |
+| <kbd>F2</kbd>  |  Go to definition |
+| <kbd>Cmd/Ctrl</kbd>+<kbd>I</kbd> |  Reindent selection |
+| <kbd>Cmd/Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>A</kbd> |  Reformat selection |
+| <kbd>Cmd/Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Enter</kbd> | Source current R script with echo |
+| <kbd>Cmd/Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Shift</kbd>+<kbd>M</kbd> |  Rename symbol  |
+| <kbd>Cmd/Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>I</kbd> | Insert code cell (Quarto) |
+| <kbd>Cmd/Ctrl</kbd>+<kbd>Enter</kbd> | Run current line (Quarto) |
+| <kbd>Cmd/Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Enter</kbd> | Run current cell (Quarto) |
+| <kbd>Cmd/Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>M</kbd> |  Open version control pane |
+| <kbd>Cmd/Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Left</kbd> |  Go to previous editor tab |
+| <kbd>Cmd/Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Right</kbd> |  Go to next editor tab |
+| <kbd>Cmd/Ctrl</kbd>+<kbd>D</kbd> |  Delete the current line |
+| <kbd>Cmd/Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>H</kbd> | Set working directory |
+| <kbd>Cmd/Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>R</kbd> |  Insert section |
+| <kbd>Alt</kbd>+<kbd>Shift</kbd>+<kbd>K</kbd> | Open global keybindings list |

migrate-rstudio-navigation.qmd

@@ -0,0 +1,19 @@
+---
+title: "Navigation"
+---
+
+This guide helps RStudio users adapt to Positron's methods for navigating through source code.
+
+*Based on converting everything I see here: <https://docs.posit.co/ide/user/ide/guide/code/code-navigation.html>*
+
+| Navigation Task | RStudio | Closest equivalent in Positron |
+| --------------- | ------- | -------- |
+| Find in Files | <kbd>Ctrl/Cmd</kbd>+<kbd>Shift</kbd>+<kbd>F</kbd> | <kbd>Ctrl/Cmd</kbd>+<kbd>Shift</kbd>+<kbd>F</kbd> <br> [Search across files](https://code.visualstudio.com/docs/editor/codebasics#_search-across-files) |
+| Go to File | <kbd>Ctrl/Cmd</kbd>+<kbd>.</kbd> | <kbd>Ctrl/Cmd</kbd>+<kbd>P</kbd> <br> [Quick open](https://code.visualstudio.com/docs/editing/editingevolved#_quick-file-navigation)|
+| Go to Function/Symbol | <kbd>Ctrl/Cmd</kbd>+<kbd>.</kbd> | With RStudio keybindings enabled: <br> <kbd>Ctrl/Cmd</kbd>+<kbd>.</kbd><br><br>In all configurations: <br> <kbd>Ctrl/Cmd</kbd>+<kbd>T</kbd> <br>[Go to Symbol in Workspace](https://code.visualstudio.com/docs/editor/editingevolved#_go-to-symbol)<br><br><kbd>Ctrl/Cmd</kbd>+<kbd>Shift</kbd>+<kbd>O</kbd> (symbols in current file) |
+| Go to Function Definition | <kbd>Ctrl/Cmd</kbd> + click or <kbd>F2</kbd> | With RStudio keybindings enabled: <br> <kbd>Ctrl/Cmd</kbd> + click <br><br> In all configurations: <br> <kbd>F2</kbd> |
+| Jump to Line | <kbd>Alt/Option</kbd>+<kbd>Shift</kbd>+<kbd>G</kbd> | <kbd>Ctrl</kbd>+<kbd>G</kbd> |
+| Navigate Back or Forward | <kbd>Ctrl/Cmd</kbd>+<kbd>F9</kbd> <br> <kbd>Ctrl/Cmd</kbd>+<kbd>F10</kbd> | Windows/Linux: <br> <kbd>Alt</kbd>+<kbd>Left</kbd><br> <kbd>Alt</kbd>+<kbd>Right</kbd> <br><br> Mac: <br> <kbd>Ctrl</kbd>+<kbd>-</kbd> <br> <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>-</kbd> |
+| Focus Previous or Next Editor Tab | <kbd>Ctrl/Cmd</kbd>+<kbd>Alt</kbd>+<kbd>Left</kbd> <br> <kbd>Ctrl/Cmd</kbd>+<kbd>Alt</kbd>+<kbd>Right</kbd> | With RStudio keybindings enabled: <br> <kbd>Ctrl/Cmd</kbd>+<kbd>Alt</kbd>+<kbd>Left</kbd> <br> <kbd>Ctrl/Cmd</kbd>+<kbd>Alt</kbd>+<kbd>Right</kbd> |
+
+*TO DISCUSS: say anything about the outline? Or breadcrumbs? This feels like an active area of folks asking questions and opening issues, based on some friction in their RStudio to Positron migration journey.*