Rework website to be easier to navigate

posit-dev · Jan 21, 2025 · f4ba2c1 · f4ba2c1
1 parent bd7bec7
commit f4ba2c1
Show file tree

Hide file tree

Showing 9 changed files with 174 additions and 164 deletions.
diff --git a/README.md b/README.md
@@ -4,13 +4,13 @@ Air <img src="docs/images/air.png" align="right" height=160 />
 [![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:
 
@@ -31,35 +31,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).
diff --git a/docs-old/release.md → docs-old/developer.md b/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`.
diff --git a/docs/_quarto.yml b/docs/_quarto.yml
@@ -10,20 +10,20 @@ 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
   margin-header: |
     <img src="/images/air.png" alt="Logo" width="150"/>
 

diff --git a/docs/installation.qmd → docs/cli.qmd b/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).
diff --git a/docs/editor-rstudio.qmd b/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.
diff --git a/docs/editor-vscode.qmd b/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 -->
diff --git a/docs/editors.qmd b/docs/editors.qmd
@@ -1,5 +1,5 @@
 ---
-title: "Editor setup"
+title: "Editor support"
 editor:
   markdown:
     wrap: sentence
@@ -9,115 +9,10 @@ editor:
 Air provides excellent support for code editors that support the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/).
 Many do, including [Positron](https://positron.posit.co/), [VS Code](https://code.visualstudio.com/), and [Zed](https://zed.dev/).
 Air also provides some support for code editors that allow for external formatters, such as [RStudio](https://posit.co/products/open-source/rstudio/).
+Follow one of our editor specific guides to get set up with Air in your preferred editor:
 
-```{=html}
-<!--
-# Uncomment after we support this
+-   [VS Code](editor-vscode.qmd)
 
-For both Positron and VS Code, Air provides a first class VS Code Extension, installable through either the VS Code Marketplace, or through OpenVSX. For other editors that support the LSP, there may be additional setup required.
- -->
-```
+-   [Positron](editor-vscode.qmd)
 
-# VS Code {#vs-code}
-
-Our VS Code extension does not yet bundle the Air binary, so the first thing you need to do is [install the Air binary](installation.qmd).
-After you install the Air binary, the extension will automatically find it.
-
-We don't currently have a VS Code Extension on the marketplace yet, but we do build them as artifacts on each commit.
-The short-term way to install the extension is to open this link in your browser, which will download a zip folder containing the extension as a vsix file:
-
-<https://github.com/posit-dev/air/actions/runs/12417189172/artifacts/2344425762>
-
-After downloading the extension, open VS Code, navigate to the Extensions pane, and drag the vsix file into the Extensions pane and "drop" it in.
-VS Code will automatically recognize it and install the extension.
-
-## 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 may also want to set Air as the default formatter for R documents if you have multiple R formatters installed.
-You can set that with `"editor.defaultFormatter": "Posit.air"`.
-
-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 -->
-
-# Positron
-
-Follow the instructions for [VS Code](#vs-code).
-
-Eventually the Air extension will be available on OpenVSX for easy use in Positron.
-
-# RStudio
-
-As of RStudio 2024.12.0, there is experimental support for an "external formatter".
-
-RStudio does not bundle an Air binary, so the first thing you need to do is [install the Air binary](installation.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 Mac or Linux, 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"}
-
-## 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 images -->
-
-# 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.
-
-There is currently no way to use Air in RStudio with Quarto documents.
-
-## 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 -->
+-   [RStudio](editor-rstudio.qmd)