Rework website to be easier to navigate

README.md

@@ -1,15 +1,15 @@
-# air
+# Air
 
 [![Actions status](https://github.com/posit-dev/air/actions/workflows/test.yml/badge.svg)](https://github.com/posit-dev/air/actions)
 
 > [!NOTE]
-> air is currently in alpha. Expect breaking changes both in the API and in formatting results.
+> Air is currently in alpha. Expect breaking changes both in the API and in formatting results. We also recommend that you use a version control system like git so you can easily see the changes that Air makes.
 
 An R formatter and language server, written in Rust.
 
 # Installation
 
-Install air using our standalone installers.
+Air is usable both as a command line tool and as a language server inside your favorite code editors. If you'd like to use Air within a code editor, we recommend reading our [editors guide](https://posit-dev.github.io/air/editors.html). If you'd just like to use Air from the command line, you can install Air using our standalone installers.
 
 On macOS and Linux:
 
@@ -30,35 +30,10 @@ curl -LsSf https://github.com/posit-dev/air/releases/download/0.1.1/air-installe
 powershell -c "irm https://github.com/posit-dev/air/releases/download/0.1.1/air-installer.ps1 | iex"
 ```
 
-The installer scripts will automatically add air to your `PATH`. The very first time you install air, you'll need to restart your shell for the `PATH` modifications to be applied.
+The installer scripts will automatically add Air to your `PATH`. The very first time you install Air, you'll need to restart your shell for the `PATH` modifications to be applied.
 
 # Acknowledgements and inspiration
 
-air draws inspiration from many sources including [roslyn](https://github.com/dotnet/roslyn), [swift](https://github.com/swiftlang/swift), [rust-analyzer](https://github.com/rust-lang/rust-analyzer), [prettier](https://github.com/prettier/prettier), [biome](https://github.com/biomejs/biome), and [ruff](https://github.com/astral-sh/ruff). These are all excellent tools that provide either formatters, language servers, or both, all of which have influenced design decisions in air.
+Air draws inspiration from many sources including [rust-analyzer](https://github.com/rust-lang/rust-analyzer), [prettier](https://github.com/prettier/prettier), [biome](https://github.com/biomejs/biome), and [ruff](https://github.com/astral-sh/ruff). These are all excellent tools that provide either formatters, language servers, or both, all of which have influenced design decisions in Air.
 
-We are particularly thankful to [biome](https://github.com/biomejs/biome), as air is built on top of their language agnostic tooling for both building a [rowan](https://github.com/rust-analyzer/rowan) syntax tree and implementing a formatter. Biome is an open source project maintained by community members, please consider [sponsoring them](https://github.com/sponsors/biomejs#sponsors).
-
-# Developer notes
-
-Install the dev version of the air cli with:
-
-```sh
-cargo install --path crates/air --debug
-```
-
-This installs it to `~/.cargo/bin` (which must be on your `PATH`), and can be removed with `cargo uninstall air`.
-
-Install the dev version of the VS Code extension:
-
-```sh
-# The first time
-npm install --global vsce
-
-# Install for Positron
-cd editors/code && rm -rf *.vsix && vsce package && positron --install-extension *.vsix
-
-# Install for VS Code
-cd editors/code && rm -rf *.vsix && vsce package && code --install-extension *.vsix
-```
-
-The CLI tools for Positron or VS Code need to be installed on your path using the command palette command `Shell Command: Install 'code'/'positron' command in PATH`.
+We are particularly thankful to [biome](https://github.com/biomejs/biome), as Air is built on top of their language agnostic tooling for both building a [rowan](https://github.com/rust-analyzer/rowan) syntax tree and implementing a formatter. Biome is an open source project maintained by community members, please consider [sponsoring them](https://github.com/sponsors/biomejs#sponsors).

docs-old/release.md → docs-old/developer.md

@@ -1,4 +1,4 @@
-# CLI
+# Release
 
 The release process of the air cli has some manual steps. One complication is that for each release of the CLI binary, we create a new release of the extension as this is our primary way of distributing Air.
 
@@ -35,3 +35,28 @@ When you want to cut a release:
   It runs on `workflow_dispatch`, and automatically pulls in the latest release binary of Air from the binary release workflow above.
 
 There is no need to bump to an intermediate "dev version" after a release.
+
+# Development installation
+
+Install the dev version of the Air cli with:
+
+```sh
+cargo install --path crates/air --debug
+```
+
+This installs it to `~/.cargo/bin` (which must be on your `PATH`), and can be removed with `cargo uninstall air`.
+
+Install the dev version of the VS Code extension:
+
+```sh
+# The first time
+npm install --global vsce
+
+# Install for Positron
+cd editors/code && rm -rf *.vsix && vsce package && positron --install-extension *.vsix
+
+# Install for VS Code
+cd editors/code && rm -rf *.vsix && vsce package && code --install-extension *.vsix
+```
+
+The CLI tools for Positron or VS Code need to be installed on your path using the command palette command `Shell Command: Install 'code'/'positron' command in PATH`.

docs/_quarto.yml

@@ -10,21 +10,21 @@ website:
     style: "floating"
     search: true
     contents:
-      - text: "Overview"
+      - text: "Air"
         href: index.qmd
 
-      - text: "Installation"
-        href: installation.qmd
+      - text: "Command line"
+        href: cli.qmd
 
-      - text: "Editors"
+      - section: "Editors"
         href: editors.qmd
+        contents:
+          - editor-rstudio.qmd
+          - editor-vscode.qmd
 
       - text: "Configuration"
         href: configuration.qmd
 
-      - text: "Formatter"
-        href: formatter.qmd
-
 format:
   html:
     theme:

docs/installation.qmd → docs/cli.qmd

@@ -1,22 +1,14 @@
 ---
-title: "Installing Air"
+title: "Command line interface"
 editor:
   markdown:
     wrap: sentence
     canonical: true
 ---
 
-If you'd like to use Air at the command line, you can use one of our standalone installers.
-
-```{=html}
-<!--
-# Uncomment after we support this
-
-Note that if you'd like to use Air inside VS Code or Positron, then the Extension for those editors comes pre-bundled with an Air binary, so there's nothing you need to do besides [download the Extension](editors.qmd).
--->
-```
+# Installation
 
-To install Air as a command line tool:
+If you'd like to use Air at the command line, you can use one of our standalone installers.
 
 On macOS and Linux:
 
@@ -39,3 +31,5 @@ powershell -c "irm https://github.com/posit-dev/air/releases/download/0.1.1/air-
 
 The installer scripts will automatically add Air to your `PATH`.
 The very first time you install Air, for the `PATH` modifications to be applied you'll need to restart your terminal.
+
+Note that if you'd like to use Air inside VS Code or Positron, then the Extension for those editors comes pre-bundled with an Air binary, so there's nothing you need to do besides [download the Extension](editor-vscode.qmd).

docs/editor-rstudio.qmd

@@ -0,0 +1,45 @@
+---
+title: "RStudio"
+editor:
+  markdown:
+    wrap: sentence
+    canonical: true
+---
+
+RStudio does not support the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/), but you can still use Air as an *external formatter*.
+
+# Installation
+
+::: callout-note
+## Air is currently only supported on macOS and Windows. Linux support is coming soon!
+:::
+
+Ensure you have at least RStudio version 2024.12.0, which you can download from [here](https://posit.co/download/rstudio-desktop/).
+Additionally, you'll need to install the Air [command line tool](cli.qmd).
+
+Open `Tools -> Global Options -> Code` and change the option to use an `External` formatter.
+Then set the `Reformat command` to {`path/to/air} format`.
+
+The easiest way to figure out `{path/to/air}` for yourself is to run `which air` from a Terminal on Unix, and `where air` from the Command Prompt on Windows.
+
+![](./images/rstudio-external-formatter.png){fig-alt="Setting Air as an external formatter with Tools -> Global Options -> Code -> Formatting" fig-align="center"}
+
+# Features
+
+## Format on save
+
+After you've set Air as an external formatter, you can either tell RStudio to format all documents on save, or set this on a per document basis.
+
+To format all documents on save, open `Tools -> Global Options -> Code -> Saving` and check `Reformat documents on save`.
+
+![](images/rstudio-format-on-save.png){fig-alt="Setting RStudio to format all documents on save in Tools -> Global Options -> Code -> Saving" fig-align="center"}
+
+To format individual documents on save, open the file specific settings and check `Reformat Document on Save`.
+
+![](images/rstudio-reformat-document-on-save.png){fig-align="center"}
+
+<!--# Come back and add video of formatting in action -->
+
+## Quarto
+
+There is currently no way to use Air in RStudio with Quarto documents.

docs/editor-vscode.qmd

@@ -0,0 +1,73 @@
+---
+title: "VS Code and Positron"
+editor:
+  markdown:
+    wrap: sentence
+    canonical: true
+---
+
+Air provides first class support for both VS Code and Positron, which both support the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/).
+
+# Installation
+
+::: callout-note
+## Air is currently only supported on macOS and Windows. Linux support is coming soon!
+:::
+
+Air is available [as an Extension](https://marketplace.visualstudio.com/items?itemName=Posit.air-vscode) for both VS Code and Positron.
+The extension comes pre-bundled with an Air binary, so you don't need anything else to get going!
+The Air extension is hosted in the VS Code Marketplace and on OpenVSX.
+
+# Features
+
+## Format on save
+
+Once you have the extension installed, turn on Format on Save for R documents by opening your `settings.json` and adding:
+
+``` json
+{
+    "[r]": {
+        "editor.formatOnSave": true
+    }
+}
+```
+
+You should now be able to simply open an R document, save it, and have the entire document formatted by Air.
+You can also explicitly call the command `Format Document` if you'd like to control this manually.
+
+<!--# Come back and add video -->
+
+## Format selection
+
+To format a selection of code, highlight it with your cursor and run the command `Format Selection`.
+Formatting a selection may *expand* that selection to find the nearest complete fragment of code that is formattable.
+
+<!--# Come back and add video -->
+
+## Quarto
+
+Quarto support currently only works in VS Code.
+There is an [issue](https://github.com/posit-dev/air/issues/77) in VS Code itself that currently prevents it from working correctly in Positron, we will fix this in Positron soon.
+
+### Format on save
+
+To format all R code cells on save, set this in your `settings.json`:
+
+``` json
+{
+    "[quarto]": {
+        "editor.formatOnSave": true
+    },
+    "[r]": {
+        "editor.formatOnSave": true
+    }
+}
+```
+
+<!--# Come back and add video -->
+
+### Format cell
+
+When inside an R cell in a Quarto document, use the chorded key combination `Cmd+K Cmd+F` or the command `Quarto: Format Cell` to format a single cell.
+
+<!--# Come back and add video -->