refactor(docs): clean up and restructure

2021-07-07 11:00:51 -05:00 · 2021-07-07 11:00:51 -05:00 · 66b6590e36
parent a96e16e593
commit 66b6590e36
13 changed files with 1274 additions and 1113 deletions
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@ -2,17 +2,16 @@
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 # Contributing
 - [Pull Requests](#pull-requests)
  - [Commits](#commits)
 - [Requirements](#requirements)
- [Development Workflow](#development-workflow)
+- [Creating pull requests](#creating-pull-requests)
-  - [Updating VS Code](#updating-vs-code)
+  - [Commits and commit history](#commits-and-commit-history)
-    - [Notes about Changes](#notes-about-changes)
+- [Development workflow](#development-workflow)
- [Build](#build)
+  - [Updates to VS Code](#updates-to-vs-code)
- [Testing](#testing)
+  - [Build](#build)
-  - [Unit Tests](#unit-tests)
+  - [Test](#test)
-  - [Integration Tests](#integration-tests)
+  - [Unit tests](#unit-tests)
-  - [End-to-End Tests](#end-to-end-tests)
+  - [Integration tests](#integration-tests)
  - [End-to-end tests](#end-to-end-tests)
 - [Structure](#structure)
  - [Modifications to VS Code](#modifications-to-vs-code)
  - [Currently Known Issues](#currently-known-issues)
@ -21,41 +20,49 @@
 - [Detailed CI and build process docs](../ci)
 ## Pull Requests
 Please create a [GitHub Issue](https://github.com/cdr/code-server/issues) to address any issue. You can skip this if the proposed fix is minor.
 In your Pull Requests (PR), link to the issue that the PR solves.
 Please ensure that the base of your PR is the **main** branch.
 ### Commits
 We prefer a clean commit history. This means you should squash all fixups and fixup-type commits before asking for review (cleanup, squash, force-push). If you need help with this, feel free to leave a comment in your PR and we'll guide you.
 ## Requirements
-The prerequisites for contributing to code-server are almost the same as those for
+The prerequisites for contributing to code-server are almost the same as those
-[VS Code](https://github.com/Microsoft/vscode/wiki/How-to-Contribute#prerequisites).
+for [VS
-There are several differences, however. Here is what is needed:
+Code](https://github.com/Microsoft/vscode/wiki/How-to-Contribute#prerequisites).
 Here is what is needed:
 - `node` v14.x
 - `git` v2.x or greater
 - [`yarn`](https://classic.yarnpkg.com/en/)
-  - used to install JS packages and run scripts
+  - Used to install JS packages and run scripts
 - [`nfpm`](https://classic.yarnpkg.com/en/)
-  - used to build `.deb` and `.rpm` packages
+  - Used to build `.deb` and `.rpm` packages
 - [`jq`](https://stedolan.github.io/jq/)
-  - used to build code-server releases
+  - Used to build code-server releases
 - [`gnupg`](https://gnupg.org/index.html)
-  - all commits must be signed and verified
+  - All commits must be signed and verified; see GitHub's [Managing commit
-  - see GitHub's ["Managing commit signature verification"](https://docs.github.com/en/github/authenticating-to-github/managing-commit-signature-verification) or follow [this tutorial](https://joeprevite.com/verify-commits-on-github)
+    signature
- `build-essential` (Linux)
+    verification](https://docs.github.com/en/github/authenticating-to-github/managing-commit-signature-verification)
-  - `apt-get install -y build-essential` - used by VS Code
+    or follow [this tutorial](https://joeprevite.com/verify-commits-on-github)
 - `build-essential` (Linux only - used by VS Code)
  - Get this by running `apt-get install -y build-essential`
 - `rsync` and `unzip`
-  - used for code-server releases
+  - Used for code-server releases
-## Development Workflow
+## Creating pull requests
 Please create a [GitHub Issue](https://github.com/cdr/code-server/issues) that
 includes context for issues that you see. You can skip this if the proposed fix
 is minor.
 In your pull requests (PR), link to the issue that the PR solves.
 Please ensure that the base of your PR is the **main** branch.
 ### Commits and commit history
 We prefer a clean commit history. This means you should squash all fixups and
 fixup-type commits before asking for a review (e.g., clean up, squash, then force
 push). If you need help with this, feel free to leave a comment in your PR, and
 we'll guide you.
 ## Development workflow
 ```shell
 yarn
@ -65,28 +72,30 @@ yarn watch
 `yarn watch` will live reload changes to the source.
-### Updating VS Code
+### Updates to VS Code
-Updating VS Code requires `git subtree`. On some rpm-based Linux distros, `git subtree` is not included by default, and needs to be installed separately.
+Updating VS Code requires `git subtree`. On some RPM-based Linux distros, `git subtree` is not included by default and needs to be installed separately. To
-To install, run `dnf install git-subtree` or `yum install git-subtree` as necessary.
+install, run `dnf install git-subtree` or `yum install git-subtree`.
-To update VS Code, follow these steps:
+To update VS Code:
 1. Run `yarn update:vscode`.
-2. Enter a version. Ex. 1.53
+2. Enter a version (e.g., `1.53`)
-3. This will open a draft PR for you.
+3. This will open a draft pull request for you.
-4. There will be merge conflicts. First commit them.
+4. There will be merge conflicts. Commit them first, since it will be impossible
-   1. We do this because if we don't, it will be impossible to review your PR.
+   for us to review your PR if you don't.
-5. Once they're all fixed, test code-server locally and make sure it all works.
+5. Fix the conflicts. Then, test code-server locally to make sure everything
-6. Check the version of Node.js that the version of Electron shipped with VSCode uses, and update the version of Node.js if necessary.
+   works.
 6. Check the Node.js version that's used by Electron (which is shipped with VS
   Code. If necessary, update your version of Node.js to match.
-#### Notes about Changes
+> Watch for updates to
 > `lib/vscode/src/vs/code/browser/workbench/workbench.html`. You may need to
 > make changes to `src/browser/pages/vscode.html`.
- watch out for updates to `lib/vscode/src/vs/code/browser/workbench/workbench.html`. You may need to make changes to `src/browser/pages/vscode.html`
+### Build
-## Build
+You can build as follows:
 You can build using:
 ```shell
 yarn build
@ -94,7 +103,7 @@ yarn build:vscode
 yarn release
 ```
-Run your build with:
+Run your build:
 ```shell
 cd release
@ -111,73 +120,88 @@ yarn test:standalone-release
 yarn package
 ```
-NOTE: On Linux, the currently running distro will become the minimum supported version.
+> On Linux, the currently running distro will become the minimum supported
-In our GitHub Actions CI, we use CentOS 7 for maximum compatibility.
+> version. In our GitHub Actions CI, we use CentOS 7 for maximum compatibility.
-If you need your builds to support older distros, run the build commands
+> If you need your builds to support older distros, run the build commands
-inside a Docker container with all the build requirements installed.
+> inside a Docker container with all the build requirements installed.
-## Testing
+### Test
 There are three kinds of tests in code-server:
-1. unit tests
+1. Unit tests
-2. integration tests
+2. Integration tests
-3. end-to-end tests
+3. End-to-end tests
-### Unit Tests
+### Unit tests
-Our unit tests are written in TypeScript and run using [Jest, the testing framework](https://jestjs.io/).
+Our unit tests are written in TypeScript and run using
 [Jest](https://jestjs.io/), the testing framework].
 These live under [test/unit](../test/unit).
 We use unit tests for functions and things that can be tested in isolation.
-### Integration Tests
+### Integration tests
-These are a work-in-progress. We build code-server and run a script called [test-standalone-release.sh`](../ci/build/test-standalone-release.sh)
+These are a work in progress. We build code-server and run a script called
-which ensures that code-server's CLI is working.
+[test-standalone-release.sh](../ci/build/test-standalone-release.sh), which
 ensures that code-server's CLI is working.
-Integration for us means testing things that integrate and rely on each other. For instance, testing the CLI which requires that code-server be built and packaged.
+Our integration tests look at components that rely on one another. For example,
 testing the CLI requires us to build and package code-server.
-### End-to-End Tests
+### End-to-end tests
-The end-to-end (e2e) are written in TypeScript and run using [Playwright](https://playwright.dev/).
+The end-to-end (e2e) tests are written in TypeScript and run using
 [Playwright](https://playwright.dev/).
 These live under [test/e2e](../test/e2e).
-Before the e2e tests run, we have a `globalSetup` that runs which makes it so you don't have to login before each test and can reuse the authentication state.
+Before the e2e tests run, we run `globalSetup`, which eliminates the need to log
 in before each test by preserving the authentication state.
-Take a look at `codeServer.test.ts` to see how you use it (look at `test.use`).
+Take a look at `codeServer.test.ts` to see how you would use it (see
 `test.use`).
-We also have a model where you can create helpers to use within tests. Take a look at [models/CodeServer.ts](../test/e2e/models/CodeServer.ts) to see an example.
+We also have a model where you can create helpers to use within tests. See
 [models/CodeServer.ts](../test/e2e/models/CodeServer.ts) for an example.
-Generally speaking, e2e means testing code-server running in the browser, similar to how a user would interact with it. When running these tests with `yarn test:e2e`, you must have code-server running locally. In CI, this is taken care of for you.
+Generally speaking, e2e means testing code-server while running in the browser
 and interacting with it in a way that's similar to how a user would interact
 with it. When running these tests with `yarn test:e2e`, you must have
 code-server running locally. In CI, this is taken care of for you.
 ## Structure
-The `code-server` script serves an HTTP API for login and starting a remote VS Code process.
+The `code-server` script serves as an HTTP API for login and starting a remote VS
 Code process.
-The CLI code is in [src/node](../src/node) and the HTTP routes are implemented in
+The CLI code is in [src/node](../src/node) and the HTTP routes are implemented
-[src/node/routes](../src/node/routes).
+in [src/node/routes](../src/node/routes).
-Most of the meaty parts are in the VS Code portion of the codebase under [lib/vscode](../lib/vscode), which we described next.
+Most of the meaty parts are in the VS Code portion of the codebase under
 [lib/vscode](../lib/vscode), which we describe next.
 ### Modifications to VS Code
-In v1 of code-server, we had a patch of VS Code that split the codebase into a front-end
+In v1 of code-server, we had a patch of VS Code that split the codebase into a
-and a server. The front-end consisted of all UI code, while the server ran the extensions
+front-end and a server. The front-end consisted of the UI code, while the server
-and exposed an API to the front-end for file access and all UI needs.
+ran the extensions and exposed an API to the front-end for file access and all
 UI needs.
-Over time, Microsoft added support to VS Code to run it on the web. They have made
+Over time, Microsoft added support to VS Code to run it on the web. They have
-the front-end open source, but not the server. As such, code-server v2 (and later) uses
+made the front-end open source, but not the server. As such, code-server v2 (and
-the VS Code front-end and implements the server. We do this by using a git subtree to fork and modify VS Code. This code lives under [lib/vscode](../lib/vscode).
+later) uses the VS Code front-end and implements the server. We do this by using
 a Git subtree to fork and modify VS Code. This code lives under
 [lib/vscode](../lib/vscode).
-Some noteworthy changes in our version of VS Code:
+Some noteworthy changes in our version of VS Code include:
 - Adding our build file, which includes our code and VS Code's web code
 - Allowing multiple extension directories (both user and built-in)
- Modifying the loader, websocket, webview, service worker, and asset requests to
+- Modifying the loader, WebSocket, webview, service worker, and asset requests to
-  use the URL of the page as a base (and TLS, if necessary for the websocket)
+  use the URL of the page as a base (and TLS, if necessary for the WebSocket)
 - Sending client-side telemetry through the server
 - Allowing modification of the display language
 - Making it possible for us to load code on the client
@ -191,7 +215,7 @@ us to ensure that our changes are still applied and work as intended. In the fut
 we'd like to run VS Code unit tests against our builds to ensure that features
 work as expected.
-**Note**: We have [extension docs](../ci/README.md) on the CI and build system.
+> We have [extension docs](../ci/README.md) on the CI and build system.
 If the functionality you're working on does NOT depend on code from VS Code, please
 move it out and into code-server.
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@ -3,160 +3,139 @@
 # FAQ
 - [Questions?](#questions)
 - [iPad Status?](#ipad-status)
 - [Community Projects (awesome-code-server)](#community-projects-awesome-code-server)
 - [How can I reuse my VS Code configuration?](#how-can-i-reuse-my-vs-code-configuration)
 - [Differences compared to VS Code?](#differences-compared-to-vs-code)
  - [Installing an extension](#installing-an-extension)
 - [How can I request a missing extension?](#how-can-i-request-a-missing-extension)
 - [Installing an extension manually](#installing-an-extension-manually)
 - [How do I configure the marketplace URL?](#how-do-i-configure-the-marketplace-url)
 - [Where are extensions stored?](#where-are-extensions-stored)
 - [How is this different from VS Code Codespaces?](#how-is-this-different-from-vs-code-codespaces)
 - [How should I expose code-server to the internet?](#how-should-i-expose-code-server-to-the-internet)
- [Can I store my password hashed?](#can-i-store-my-password-hashed)
+- [Can I use code-server on the iPad?](#can-i-use-code-server-on-the-ipad)
 - [How do I securely access web services?](#how-do-i-securely-access-web-services)
  - [Sub-paths](#sub-paths)
  - [Sub-domains](#sub-domains)
 - [Why does the code-server proxy strip `/proxy/<port>` from the request path?](#why-does-the-code-server-proxy-strip-proxyport-from-the-request-path)
  - [Proxying to Create React App](#proxying-to-create-react-app)
 - [Multi-tenancy](#multi-tenancy)
 - [Docker in code-server container?](#docker-in-code-server-container)
 - [How can I disable telemetry?](#how-can-i-disable-telemetry)
 - [How does code-server decide what workspace or folder to open?](#how-does-code-server-decide-what-workspace-or-folder-to-open)
 - [How do I debug issues with code-server?](#how-do-i-debug-issues-with-code-server)
 - [Heartbeat File](#heartbeat-file)
 - [Healthz endpoint](#healthz-endpoint)
 - [How does the config file work?](#how-does-the-config-file-work)
 - [Isn't an install script piped into sh insecure?](#isnt-an-install-script-piped-into-sh-insecure)
 - [How do I make my keyboard shortcuts work?](#how-do-i-make-my-keyboard-shortcuts-work)
- [How do I access my Documents/Downloads/Desktop folders in code-server on OSX?](#how-do-i-access-my-documentsdownloadsdesktop-folders-in-code-server-on-osx)
+- [Why can't code-server use Microsoft's extension marketplace?](#why-cant-code-server-use-microsofts-extension-marketplace)
- [Differences compared to Theia?](#differences-compared-to-theia)
+- [How can I request an extension that's missing from the marketplace?](#how-can-i-request-an-extension-thats-missing-from-the-marketplace)
- [`$HTTP_PROXY`, `$HTTPS_PROXY`, `$NO_PROXY`](#http_proxy-https_proxy-no_proxy)
+- [How do I install an extension?](#how-do-i-install-an-extension)
 - [How do I install an extension manually?](#how-do-i-install-an-extension-manually)
 - [How do I use my own extensions marketplace?](#how-do-i-use-my-own-extensions-marketplace)
 - [Where are extensions stored?](#where-are-extensions-stored)
 - [How can I reuse my VS Code configuration?](#how-can-i-reuse-my-vs-code-configuration)
 - [How does code-server decide what workspace or folder to open?](#how-does-code-server-decide-what-workspace-or-folder-to-open)
 - [How do I access my Documents/Downloads/Desktop folders in code-server on macOS?](#how-do-i-access-my-documentsdownloadsdesktop-folders-in-code-server-on-macos)
 - [How do I direct server-side requests through a proxy?](#how-do-i-direct-server-side-requests-through-a-proxy)
 - [How do I debug issues with code-server?](#how-do-i-debug-issues-with-code-server)
 - [What is the healthz endpoint?](#what-is-the-healthz-endpoint)
 - [What is the heartbeat file?](#what-is-the-heartbeat-file)
 - [How do I change the password?](#how-do-i-change-the-password)
 - [Can I store my password hashed?](#can-i-store-my-password-hashed)
 - [Is multi-tenancy possible?](#is-multi-tenancy-possible)
 - [Can I use Docker in a code-server container?](#can-i-use-docker-in-a-code-server-container)
 - [How do I disable telemetry?](#how-do-i-disable-telemetry)
 - [What's the difference between code-server and Theia?](#whats-the-difference-between-code-server-and-theia)
 - [What's the difference between code-server and VS Code Codespaces?](#whats-the-difference-between-code-server-and-vs-code-codespaces)
 - [Does code-server have any security login validation?](#does-code-server-have-any-security-login-validation)
 - [Enterprise](#enterprise)
 - [Are there community projects involving code-server?](#are-there-community-projects-involving-code-server)
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 ## Questions?
-Please file all questions and support requests at <https://github.com/cdr/code-server/discussions>.
+Please file all questions and support requests at
 <https://github.com/cdr/code-server/discussions>.
-## iPad Status?
+## How should I expose code-server to the internet?
-Please see [./ipad.md](./ipad.md).
+Please see [our instructions on exposing code-server safely to the
 internet](./guide.md).
-## Community Projects (awesome-code-server)
+## Can I use code-server on the iPad?
-Visit the [awesome-code-server](https://github.com/cdr/awesome-code-server) repository to view community projects and guides with code-server! Feel free to add your own!
+See [iPad](./ipad.md) for information on using code-server on the iPad.
-## How can I reuse my VS Code configuration?
+## How does the config file work?
-The very popular [Settings Sync](https://marketplace.visualstudio.com/items?itemName=Shan.code-settings-sync) extension works.
+When `code-server` starts up, it creates a default config file in `~/.config/code-server/config.yaml`:
-You can also pass `--user-data-dir ~/.vscode` to reuse your existing VS Code extensions and configuration.
+```yaml
 bind-addr: 127.0.0.1:8080
 auth: password
 password: mew...22 # Randomly generated for each config.yaml
 cert: false
 ```
-Or copy `~/.vscode` into `~/.local/share/code-server`.
+The default config defines the following behavior:
-## Differences compared to VS Code?
+- Listen on the loopback IP port 8080
 - Enable password authorization
 - Do not use TLS
-`code-server` takes the open source core of VS Code and allows you to run it in the browser.
+Each key in the file maps directly to a `code-server` flag (run `code-server --help` to see a listing of all the flags). Any flags passed to `code-server`
-However, it is not entirely equivalent to Microsoft's VS Code.
+will take priority over the config file.
-While the core of VS Code is open source, the marketplace and many published Microsoft extensions are not.
+You can change the config file's location using the `--config` flag or
 `$CODE_SERVER_CONFIG` environment variable.
-Furthermore, Microsoft prohibits the use of any non-Microsoft VS Code from accessing their marketplace.
+The default location respects `$XDG_CONFIG_HOME`.
-See the [TOS](https://cdn.vsassets.io/v/M146_20190123.39/_content/Microsoft-Visual-Studio-Marketplace-Terms-of-Use.pdf).
+## How do I make my keyboard shortcuts work?
-> Marketplace Offerings are intended for use only with Visual Studio Products and Services
+Many shortcuts will not work by default, since they'll be "caught" by the browser.
 > and you may only install and use Marketplace Offerings with Visual Studio Products and Services.
-As a result, we cannot offer any extensions on the Microsoft marketplace. Instead,
+If you use Chrome, you can work around this by installing the progressive web
-we have created our own marketplace for open source extensions.
+app (PWA):
 It works by scraping GitHub for VS Code extensions and building them. It's not perfect but getting
 better by the day with more and more extensions.
-These are the closed source extensions presently unavailable:
+1. Start the editor
 2. Click the **plus** icon in the URL toolbar to install the PWA
-1. [Live Share](https://visualstudio.microsoft.com/services/live-share)
+For other browsers, you'll have to remap keybindings for shortcuts to work.
   - We may implement something similar, see [#33](https://github.com/cdr/code-server/issues/33)
 1. [Remote Extensions (SSH, Containers, WSL)](https://github.com/microsoft/vscode-remote-release)
   - We may reimplement these at some point, see [#1315](https://github.com/cdr/code-server/issues/1315)
-For more about the closed source parts of VS Code, see [vscodium/vscodium](https://github.com/VSCodium/vscodium#why-does-this-exist).
+## Why can't code-server use Microsoft's extension marketplace?
-### Installing an extension
+Though code-server takes the open-source core of VS Code and allows you to run
 it in the browser, it is not entirely equivalent to Microsoft's VS Code.
-Extensions can be installed from the marketplace using the extensions sidebar in
+One major difference is in regards to extensions and the marketplace. The core
 of VS code is open source, while the marketplace and many published Microsoft
 extensions are not. Furthermore, Microsoft prohibits the use of any
 non-Microsoft VS Code from accessing their marketplace. Per the [Terms of
 Service](https://cdn.vsassets.io/v/M146_20190123.39/_content/Microsoft-Visual-Studio-Marketplace-Terms-of-Use.pdf):
 > Marketplace Offerings are intended for use only with Visual Studio Products
 > and Services, and you may only install and use Marketplace Offerings with
 > Visual Studio Products and Services.
 Because of this, we can't offer any extensions on Microsoft's marketplace.
 Instead, we've created a marketplace offering open-source extensions. The
 marketplace works by scraping GitHub for VS Code extensions and building them.
 These are the closed-source extensions that are presently unavailable:
 1. [Live Share](https://visualstudio.microsoft.com/services/live-share). We may
   implement something similar (see
   [#33](https://github.com/cdr/code-server/issues/33))
 1. [Remote Extensions (SSH, Containers,
   WSL)](https://github.com/microsoft/vscode-remote-release). We may implement
   these again at some point, see
   ([#1315](https://github.com/cdr/code-server/issues/1315)).
 For more about the closed source portions of VS Code, see [vscodium/vscodium](https://github.com/VSCodium/vscodium#why-does-this-exist).
 ## How can I request an extension that's missing from the marketplace?
 We are in the process of transitioning to [Open VSX](https://open-vsx.org/).
 Once we've [implemented Open
 VSX](https://github.com/eclipse/openvsx/issues/249), we can finalize this
 transition. As such, we are not currently accepting new extension requests.
 In the meantime, we suggest:
 - [Switching to Open VSX](#how-do-i-configure-the-marketplace-url) now
 - Downloading and [installing the extension manually](#installing-an-extension-manually)
 ## How do I install an extension?
 You can install extensions from the marketplace using the extensions sidebar in
 code-server or from the command line:
-```shell
+```console
 code-server --install-extension <extension id>
 # example: code-server --install-extension wesbos.theme-cobalt2
 ```
 ## How can I request a missing extension?
 We are currently in the process of transitioning to [Open VSX](https://open-vsx.org/).
 Once <https://github.com/eclipse/openvsx/issues/249>
 is implemented, we can fully make this transition. Therefore, we are no longer
 accepting new requests for extension requests.
 Instead, we suggest one of the following:
 - [Switch to Open VSX](#how-do-i-configure-the-marketplace-url) now
 - Download and [install the extension manually](#installing-an-extension-manually)
 ## Installing an extension manually
 If an extension is not available from the marketplace or does not work, you can
 grab its VSIX from its GitHub releases or build it yourself.
 Once you have downloaded the VSIX to the remote machine you can either:
 - Run the `Extensions: Install from VSIX` command in the Command Palette.
 - Use `code-server --install-extension <path to vsix>`
 You can also download extensions from the command line. For instance, downloading off OpenVSX can be done like this:
 ```shell
 SERVICE_URL=https://open-vsx.org/vscode/gallery ITEM_URL=https://open-vsx.org/vscode/item code-server --install-extension <extension id>
 ```
 ## How do I configure the marketplace URL?
 If you have your own marketplace that implements the VS Code Extension Gallery API, it is possible to
 point code-server to it by setting `$SERVICE_URL` and `$ITEM_URL`. These correspond directly
 to `serviceUrl` and `itemUrl` in VS Code's `product.json`.
 e.g. to use [open-vsx.org](https://open-vsx.org):
 ```bash
 export SERVICE_URL=https://open-vsx.org/vscode/gallery
 export ITEM_URL=https://open-vsx.org/vscode/item
 ```
 While you can technically use Microsoft's marketplace with these, please do not do so as it
 is against their terms of use. See [above](#differences-compared-to-vs-code) and this
 discussion regarding the use of the Microsoft URLs in forks:
 <https://github.com/microsoft/vscode/issues/31168#issue-244533026>
 See also [VSCodium's docs](https://github.com/VSCodium/vscodium/blob/master/DOCS.md#extensions--marketplace).
 These variables are most valuable to our enterprise customers for whom we have a self hosted marketplace product.
 ## Where are extensions stored?
 Defaults to `~/.local/share/code-server/extensions`.
 If the `XDG_DATA_HOME` environment variable is set the data directory will be
 `$XDG_DATA_HOME/code-server/extensions`. In general we try to follow the XDG directory spec.
 You can install an extension on the CLI with:
 ```bash
 # From the Coder extension marketplace
 code-server --install-extension ms-python.python
@ -164,281 +143,101 @@ code-server --install-extension ms-python.python
 code-server --install-extension downloaded-ms-python.python.vsix
 ```
-## How is this different from VS Code Codespaces?
+## How do I install an extension manually?
-VS Code Codespaces is a closed source and paid service by Microsoft. It also allows you to access
+If there's an extension unavailable in the marketplace or an extension that
-VS Code via the browser.
+doesn't work, you can download the VSIX from its GitHub releases or build it
 yourself.
-However, code-server is free, open source and can be run on any machine without any limitations.
+Once you have downloaded the VSIX to the remote machine, you can either:
-While you can self host environments with VS Code Codespaces, you still need an Azure billing
+- Run the **Extensions: Install from VSIX** command in the Command Palette.
-account and you have to access VS Code via the Codespaces web dashboard instead of directly
+- Run `code-server --install-extension <path to vsix>` in the terminal
 connecting to your instance.
-## How should I expose code-server to the internet?
+You can also download extensions using the command line. For instance,
-
+downloading from OpenVSX can be done like this:
 Please follow [./guide.md](./guide.md) for our recommendations on setting up and using code-server.
 code-server only supports password authentication natively.
 **note**: code-server will rate limit password authentication attempts at 2 a minute and 12 an hour.
 If you want to use external authentication (i.e sign in with Google) you should handle this
 with a reverse proxy using something like [Pomerium](https://www.pomerium.io/guides/code-server.html), [oauth2_proxy](https://github.com/pusher/oauth2_proxy)
 or [Cloudflare Access](https://teams.cloudflare.com/access).
 For HTTPS, you can use a self signed certificate by passing in just `--cert` or
 pass in an existing certificate by providing the path to `--cert` and the path to
 the key with `--cert-key`.
 The self signed certificate will be generated into
 `~/.local/share/code-server/self-signed.crt`.
 If `code-server` has been passed a certificate it will also respond to HTTPS
 requests and will redirect all HTTP requests to HTTPS.
 You can use [Let's Encrypt](https://letsencrypt.org/) to get a TLS certificate
 for free.
 Again, please follow [./guide.md](./guide.md) for our recommendations on setting up and using code-server.
 ## Can I store my password hashed?
 Yes you can! Set the value of `hashed-password` instead of `password`. Generate the hash with:
 ```shell
-echo -n "thisismypassword" | npx argon2-cli -e
+SERVICE_URL=https://open-vsx.org/vscode/gallery ITEM_URL=https://open-vsx.org/vscode/item code-server --install-extension <extension id>
 $argon2i$v=19$m=4096,t=3,p=1$wst5qhbgk2lu1ih4dmuxvg$ls1alrvdiwtvzhwnzcm1dugg+5dto3dt1d5v9xtlws4
 ```
-Of course replace `thisismypassword` with your actual password and **remember to put it inside quotes**!
+## How do I use my own extensions marketplace?
-Example:
+If you own a marketplace that implements the VS Code Extension Gallery API, you
 can point code-server to it by setting `$SERVICE_URL` and `$ITEM_URL`. These correspond directly
 to `serviceUrl` and `itemUrl` in VS Code's `product.json`.
-```yaml
+For example, to use [open-vsx.org](https://open-vsx.org), run:
-auth: password
+
-hashed-password: "$argon2i$v=19$m=4096,t=3,p=1$wST5QhBgk2lu1ih4DMuxvg$LS1alrVdIWtvZHwnzCM1DUGg+5DTO3Dt1d5v9XtLws4"
+```bash
 export SERVICE_URL=https://open-vsx.org/vscode/gallery
 export ITEM_URL=https://open-vsx.org/vscode/item
 ```
-## How do I securely access web services?
+Though you can technically use Microsoft's marketplace in this manner, we
 strongly discourage you from doing so since this is [against their Terms of Use](#why-cant-code-server-use-microsofts-extension-marketplace).
-code-server is capable of proxying to any port using either a subdomain or a
+For further information, see [this
-subpath which means you can securely access these services using code-server's
+discussion](https://github.com/microsoft/vscode/issues/31168#issue-244533026)
-built-in authentication.
+regarding the use of the Microsoft URLs in forks, as well as [VSCodium's
 docs](https://github.com/VSCodium/vscodium/blob/master/DOCS.md#extensions--marketplace).
-### Sub-paths
+## Where are extensions stored?
-Just browse to `/proxy/<port>/`.
+Extensions are store, by default, to `~/.local/share/code-server/extensions`.
-### Sub-domains
+If you set the `XDG_DATA_HOME` environment variable, the data directory will be
 `$XDG_DATA_HOME/code-server/extensions`. In general, we try to follow the XDG directory spec.
-You will need a DNS entry that points to your server for each port you want to
+## How can I reuse my VS Code configuration?
 access. You can either set up a wildcard DNS entry for `*.<domain>` if your domain
 name registrar supports it or you can create one for every port you want to
 access (`3000.<domain>`, `8080.<domain>`, etc).
-You should also set up TLS certificates for these subdomains, either using a
+You can use the [Settings
-wildcard certificate for `*.<domain>` or individual certificates for each port.
+Sync](https://marketplace.visualstudio.com/items?itemName=Shan.code-settings-sync)
 extension for this purpose.
-Start code-server with the `--proxy-domain` flag set to your domain.
+Alternatively, you can also pass `--user-data-dir ~/.vscode` or copy `~/.vscode`
-
+into `~/.local/share/code-server` to reuse your existing VS Code extensions and
-```
+configuration.
 code-server --proxy-domain <domain>
 ```
 Now you can browse to `<port>.<domain>`. Note that this uses the host header so
 ensure your reverse proxy forwards that information if you are using one.
 ## Why does the code-server proxy strip `/proxy/<port>` from the request path?
 HTTP servers should strive to use relative URLs to avoid needed to be coupled to the
 absolute path at which they are served. This means you must use trailing slashes on all
 paths with subpaths. See <https://blog.cdivilly.com/2019/02/28/uri-trailing-slashes>
 This is really the "correct" way things work and why the striping of the base path is the
 default. If your application uses relative URLs and does not assume the absolute path at
 which it is being served, it will just work no matter what port you decide to serve it off
 or if you put it in behind code-server or any other proxy!
 However many people prefer the cleaner aesthetic of no trailing slashes. This couples you
 to the base path as you cannot use relative redirects correctly anymore. See the above
 link.
 For users who are ok with this tradeoff, use `/absproxy` instead and the path will be
 passed as is. e.g. `/absproxy/3000/my-app-path`
 ### Proxying to Create React App
 You must use `/absproxy/<port>` with create-react-app.
 See [#2565](https://github.com/cdr/code-server/issues/2565) and
 [#2222](https://github.com/cdr/code-server/issues/2222). You will need to inform
 create-react-app of the path at which you are serving via `$PUBLIC_URL` and webpack
 via `$WDS_SOCKET_PATH`.
 e.g.
 ```sh
 PUBLIC_URL=/absproxy/3000 \
  WDS_SOCKET_PATH=$PUBLIC_URL/sockjs-node \
  BROWSER=none yarn start
 ```
 Then visit `https://my-code-server-address.io/absproxy/3000` to see your app exposed through
 code-server!
 Highly recommend using the subdomain approach instead to avoid this class of issue.
 ## Multi-tenancy
 If you want to run multiple code-servers on shared infrastructure, we recommend using virtual
 machines with a VM per user. This will easily allow users to run a docker daemon. If you want
 to use kubernetes, you'll definitely want to use [kubevirt](https://kubevirt.io) or [sysbox](https://github.com/nestybox/sysbox) to give each
 user a VM-like experience instead of just a container.
 ## Docker in code-server container?
 If you'd like to access docker inside of code-server, mount the docker socket in from `/var/run/docker.sock`.
 Install the docker CLI in the code-server container and you should be able to access the daemon!
 You can even make volume mounts work. Lets say you want to run a container and mount in
 `/home/coder/myproject` into it from inside the `code-server` container. You need to make sure
 the docker daemon's `/home/coder/myproject` is the same as the one mounted inside the `code-server`
 container and the mount will just work.
 ## How can I disable telemetry?
 Use the `--disable-telemetry` flag to completely disable telemetry. We use the
 data collected only to improve code-server.
 ## How does code-server decide what workspace or folder to open?
-code-server tries the following in order:
+code-server tries the following in this order:
-1. The `workspace` query parameter.
+1. The `workspace` query parameter
-2. The `folder` query parameter.
+2. The `folder` query parameter
-3. The workspace or directory passed on the command line.
+3. The workspace or directory passed via the command line
-4. The last opened workspace or directory.
+4. The last opened workspace or directory
-## How do I debug issues with code-server?
+## How do I access my Documents/Downloads/Desktop folders in code-server on macOS?
-First run code-server with at least `debug` logging (or `trace` to be really
+Newer versions of macOS require permission through a non-UNIX mechanism for
-thorough) by setting the `--log` flag or the `LOG_LEVEL` environment variable.
+code-server to access the Desktop, Documents, Pictures, Downloads, and other folders.
 `-vvv` and `--verbose` are aliases for `--log trace`.
-```
+You may have to give Node.js full disk access, since it doesn't implement any of the macOS permission request features natively:
 code-server --log debug
 ```
-Once this is done, replicate the issue you're having then collect logging
+1. Find where Node.js is installed on your machine
 information from the following places:
 1. The most recent files from `~/.local/share/code-server/coder-logs`.
 2. The browser console.
 3. The browser network tab.
 Additionally, collecting core dumps (you may need to enable them first) if
 code-server crashes can be helpful.
 ## Heartbeat File
 `code-server` touches `~/.local/share/code-server/heartbeat` once a minute as long
 as there is an active browser connection.
 If you want to shutdown `code-server` if there hasn't been an active connection in X minutes
 you can do so by continuously checking the last modified time on the heartbeat file and if it is
 older than X minutes, kill `code-server`.
 [#1636](https://github.com/cdr/code-server/issues/1636) will make the experience here better.
 ## Healthz endpoint
 `code-server` exposes an endpoint at `/healthz` which can be used to check
 whether `code-server` is up without triggering a heartbeat. The response will
 include a status (`alive` or `expired`) and a timestamp for the last heartbeat
 (defaults to `0`). This endpoint does not require authentication.
 ```json
 {
  "status": "alive",
  "lastHeartbeat": 1599166210566
 }
 ```
 ## How does the config file work?
 When `code-server` starts up, it creates a default config file in `~/.config/code-server/config.yaml` that looks
 like this:
 ```yaml
 bind-addr: 127.0.0.1:8080
 auth: password
 password: mewkmdasosafuio3422 # This is randomly generated for each config.yaml
 cert: false
 ```
 Each key in the file maps directly to a `code-server` flag. Run `code-server --help` to see
 a listing of all the flags.
 The default config here says to listen on the loopback IP port 8080, enable password authorization
 and no TLS. Any flags passed to `code-server` will take priority over the config file.
 The `--config` flag or `$CODE_SERVER_CONFIG` can be used to change the config file's location.
 The default location also respects `$XDG_CONFIG_HOME`.
 ## Isn't an install script piped into sh insecure?
 Please give
 [this wonderful blogpost](https://sandstorm.io/news/2015-09-24-is-curl-bash-insecure-pgp-verified-install) by
 [sandstorm.io](https://sandstorm.io) a read.
 ## How do I make my keyboard shortcuts work?
 Many shortcuts will not work by default as they'll be caught by the browser.
 If you use Chrome you can get around this by installing the PWA.
 Once you've entered the editor, click the "plus" icon present in the URL toolbar area.
 This will install a Chrome PWA and now all keybindings will work!
 For other browsers you'll have to remap keybindings unfortunately.
 ## How do I access my Documents/Downloads/Desktop folders in code-server on OSX?
 Newer versions of macOS require permission through a non-UNIX mechanism for access to the Desktop, Documents, Pictures, Downloads, and other folders.
 You may have to give Node "full disk access" since it doesn't implement any of the macOS permission request stuff natively.
 1. Find where Node is installed on your machine
   ```console
-   ➜ ~ which node
+   $ which node
   /usr/local/bin/node
   ```
-1. Grant Node Full Disk Access:
+2. Grant Node.js full disk access. Open **System Preferences** > **Security &
   Privacy** > **Privacy** > **Full Disk Access**. Then, click the 🔒 to unlock,
   click **+**, and select the Node.js binary you located in the previous step.
-Open System Preferences > Security & Privacy > Privacy (horizontal) tab > Full Disk Access (vertical) tab > Click the 🔒 to unlock > Click + and select the Node binary you located.
+See [#2794](https://github.com/cdr/code-server/issues/2794) for additional context.
-See [#2794](https://github.com/cdr/code-server/issues/2794) for context on this.
+## How do I direct server-side requests through a proxy?
-## Differences compared to Theia?
+> code-server proxies only server-side requests.
-[Theia](https://github.com/eclipse-theia/theia) is a browser IDE loosely based on VS Code. It uses the same
+To direct server-side requests through a proxy, code-server supports the
-text editor library named [Monaco](https://github.com/Microsoft/monaco-editor) and the same
+following environment variables:
 extension API but everything else is very different. It also uses [open-vsx.org](https://open-vsx.org)
 for extensions which has an order of magnitude less extensions than our marketplace.
 See [#1473](https://github.com/cdr/code-server/issues/1473).
-You can't just use your VS Code config in Theia like you can with code-server.
+- `$HTTP_PROXY`
-
+- `$HTTPS_PROXY`
-To summarize, code-server is a patched fork of VS Code to run in the browser whereas
+- `$NO_PROXY`
 Theia takes some parts of VS Code but is an entirely different editor.
 ## `$HTTP_PROXY`, `$HTTPS_PROXY`, `$NO_PROXY`
 code-server supports the standard environment variables to allow directing
 server side requests through a proxy.
 ```sh
 export HTTP_PROXY=https://134.8.5.4
@ -448,16 +247,150 @@ export HTTPS_PROXY=https://134.8.5.4
 code-server
 ```
- See [proxy-from-env](https://www.npmjs.com/package/proxy-from-env#environment-variables)
+- See
-  for a detailed reference on the various environment variables and their syntax.
+  [proxy-from-env](https://www.npmjs.com/package/proxy-from-env#environment-variables)
-  - code-server only uses the `http` and `https` protocols.
+  for a detailed reference on these environment variables and their syntax (note
- See [proxy-agent](https://www.npmjs.com/package/proxy-agent) for the various supported
+  that code-server only uses the `http` and `https` protocols).
-  proxy protocols.
+- See [proxy-agent](https://www.npmjs.com/package/proxy-agent) for information
  on on the supported proxy protocols.
-**note**: Only server side requests will be proxied! This includes fetching extensions,
+## How do I debug issues with code-server?
-requests made from extensions etc. To proxy requests from your browser you need to
+
-configure your browser separately. Browser requests would cover exploring the extension
+First, run code-server with the `debug` logging (or `trace` to be really
-marketplace.
+thorough) by setting the `--log` flag or the `LOG_LEVEL` environment variable.
 `-vvv` and `--verbose` are aliases for `--log trace`.
 First, run code-server with `debug` logging (or `trace` logging for more
 thorough messages) by setting the `--log` flag or the `LOG_LEVEL` environment
 variable.
 ```text
 code-server --log debug
 ```
 > Note that the `-vvv` and `--verbose` flags are aliases for `--log trace`.
 Next, replicate the issue you're having so that you can collect logging
 information from the following places:
 1. The most recent files from `~/.local/share/code-server/coder-logs`
 2. The browser console
 3. The browser network tab
 Additionally, collecting core dumps (you may need to enable them first) if
 code-server crashes can be helpful.
 ## What is the healthz endpoint?
 You can use the `/healthz` endpoint exposed by code-server to check whether
 code-server is running without triggering a heartbeat. The response includes a
 status (e.g., `alive` or `expired`) and a timestamp for the last heartbeat
 (the default is `0`).
 ```json
 {
  "status": "alive",
  "lastHeartbeat": 1599166210566
 }
 ```
 This endpoint doesn't require authentication.
 ## What is the heartbeat file?
 As long as there is an active browser connection, code-server touches
 `~/.local/share/code-server/heartbeat` once a minute.
 If you want to shutdown code-server if there hasn't been an active connection
 after a predetermined amount of time, you can do so by checking continuously for
 the last modified time on the heartbeat file. If it is older than X minutes (or
 whatever amount of time you'd like), you can kill code-server.
 Eventually, [#1636](https://github.com/cdr/code-server/issues/1636) will make
 this process better.
 ## How do I change the password?
 Edit the `password` field in the code-server config file at
 `~/.config/code-server/config.yaml`, then restart code-server:
 ```bash
 sudo systemctl restart code-server@$USER
 ```
 ## Can I store my password hashed?
 Yes, you can do so by setting the value of `hashed-password` instead of `password`. Generate the hash with:
 ```shell
 echo -n "thisismypassword" | npx argon2-cli -e
 $argon2i$v=19$m=4096,t=3,p=1$wst5qhbgk2lu1ih4dmuxvg$ls1alrvdiwtvzhwnzcm1dugg+5dto3dt1d5v9xtlws4
 ```
 Replace `thisismypassword` with your actual password and **remember to put it
 inside quotes**! For example:
 ```yaml
 auth: password
 hashed-password: "$argon2i$v=19$m=4096,t=3,p=1$wST5QhBgk2lu1ih4DMuxvg$LS1alrVdIWtvZHwnzCM1DUGg+5DTO3Dt1d5v9XtLws4"
 ```
 The `hashed-password` field takes precedence over `password`.
 ## Is multi-tenancy possible?
 If you want to run multiple code-servers on shared infrastructure, we recommend
 using virtual machines (provide one VM per user). This will easily allow users
 to run a Docker daemon. If you want to use Kubernetes, you'll want to
 use [kubevirt](https://kubevirt.io) or
 [sysbox](https://github.com/nestybox/sysbox) to give each user a VM-like
 experience instead of just a container.
 ## Can I use Docker in a code-server container?
 If you'd like to access Docker inside of code-server, mount the Docker socket in
 from `/var/run/docker.sock`. Then, install the Docker CLI in the code-server
 container, and you should be able to access the daemon.
 You can even make volume mounts work. Let's say you want to run a container and
 mount into `/home/coder/myproject` from inside the `code-server` container. You
 need to make sure the Docker daemon's `/home/coder/myproject` is the same as the
 one mounted inside the `code-server` container, and the mount will work.
 ## How do I disable telemetry?
 Use the `--disable-telemetry` flag to disable telemetry.
 > We use the data collected only to improve code-server.
 ## What's the difference between code-server and Theia?
 At a high level, code-server is a patched fork of VS Code that runs in the
 browser whereas Theia takes some parts of VS Code but is an entirely different
 editor.
 [Theia](https://github.com/eclipse-theia/theia) is a browser IDE loosely based
 on VS Code. It uses the same text editor library
 ([Monaco](https://github.com/Microsoft/monaco-editor)) and extension API, but
 everything else is different. Theia also uses [Open VSX](https://open-vsx.org)
 for extensions.
 Theia doesn't allow you to reuse your existing VS Code config.
 ## What's the difference between code-server and VS Code Codespaces?
 Both code-server and VS Code Codespaces allow you to access VS Code via a
 browser.
 VS Code Codespaces, however, is a closed-source, paid service offered by
 Microsoft. While you can self-host environments with VS Code Codespaces, you
 still need an Azure billing account, and you must access VS Code via the
 Codespaces web dashboard instead of connecting directly to it.
 On the other hand, code-server is free, open-source, and can be run on any
 machine with few limitations.
 <<<<<<< HEAD
 ## Does code-server have any security login validation?
@ -465,5 +398,12 @@ code-server only supports a single password and limits logins to two per minute
 ## Enterprise
-Visit [our enterprise page](https://coder.com) for more information about our
+=======
-enterprise offerings.
+
 ## Are there community projects involving code-server?
 > > > > > > > Edit code-server docs
 Visit the [awesome-code-server](https://github.com/cdr/awesome-code-server)
 repository to view community projects and guides with code-server! Feel free to
 add your own!
--- a/docs/MAINTAINING.md
+++ b/docs/MAINTAINING.md
@ -2,130 +2,157 @@
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 # Maintaining
- [Maintaining](#maintaining)
+- [Workflow](#workflow)
  - [Workflow](#workflow)
  - [Milestones](#milestones)
  - [Triage](#triage)
-    - [Project Boards](#project-boards)
+  - [Project boards](#project-boards)
-  - [Versioning](#versioning)
+- [Versioning](#versioning)
-  - [Pull Requests](#pull-requests)
+- [Pull requests](#pull-requests)
-    - [Merge Strategies](#merge-strategies)
+  - [Merge strategies](#merge-strategies)
  - [Changelog](#changelog)
-  - [Release](#release)
+- [Releases](#releases)
    - [Release Manager Rotation](#release-manager-rotation)
  - [Publishing a release](#publishing-a-release)
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 # Maintaining
 Current maintainers:
 - @code-asher
 - @oxy
 - @jsjoeio
-This document is meant to serve current and future maintainers of code-server, but also share openly our workflow for maintaining the project.
+This document is meant to serve current and future maintainers of code-server,
 as well as share our workflow for maintaining the project.
 ## Workflow
-The workflow used by code-server maintainers is one that aims to be easy to understood by the community and easy enough for new maintainers to jump in and start contributing on day one.
+The workflow used by code-server maintainers aims to be easy to understood by
 the community and easy enough for new maintainers to jump in and start
 contributing on day one.
 ### Milestones
-We operate mainly using [milestones](https://github.com/cdr/code-server/milestones). This was heavily inspired by our friends over at [vscode](https://github.com/microsoft/vscode).
+We operate mainly using
 [milestones](https://github.com/cdr/code-server/milestones). This was heavily
 inspired by our friends over at [vscode](https://github.com/microsoft/vscode).
 Here are the milestones we use and how we use them:
 - "Backlog" -> Work not yet planned for a specific release.
 - "On Deck" -> Work under consideration for upcoming milestones.
- "Backlog Candidates" -> Work that is not yet accepted for the backlog. We wait for the community to weigh in.
+- "Backlog Candidates" -> Work that is not yet accepted for the backlog. We wait
- "<0.0.0>" -> Work to be done for that version.
+  for the community to weigh in.
 - "<0.0.0>" -> Work to be done for a specific version.
-With this flow, any un-assigned issues are essentially in triage state and once triaged are either "Backlog" or "Backlog Candidates". They will eventually move to "On Deck" (or be closed). Lastly, they will end up on a version milestone where they will be worked on.
+With this flow, any un-assigned issues are essentially in triage state. Once
 triaged, issues are either "Backlog" or "Backlog Candidates". They will
 eventually move to "On Deck" (or be closed). Lastly, they will end up on a
 version milestone where they will be worked on.
 ### Triage
 We use the following process for triaging GitHub issues:
-1. a submitter creates an issue
+1. Create an issue
-1. add appropriate labels
+1. Add appropriate labels to the issue (including "needs-investigation" if we
-   1. if we need to look into it further, add "needs-investigation"
+   should look into it further)
-1. add to milestone
+1. Add the issue to a milestone
-   1. if it should be fixed soon, add to version milestone or "On Deck"
+   1. If it should be fixed soon, add to version milestone or "On Deck"
-   1. if not urgent, add to "Backlog"
+   2. If not urgent, add to "Backlog"
-   1. otherwise, add to "Backlog Candidate" if it should be considered
+   3. Otherwise, add to "Backlog Candidate" for future consideration
-### Project Boards
+### Project boards
 We use project boards for projects or goals that span multiple milestones.
-Think of this as a place to put miscellaneous things (like testing, clean up stuff, etc). As a maintainer, random todos may come up here and there. This gives you a place to add notes temporarily before opening a new issue. Given that our release milestones function off of issues, we believe tasks should have dedicated issues.
+Think of this as a place to put miscellaneous things (like testing, clean up
 stuff, etc). As a maintainer, random tasks may come up here and there. The
 project boards give you places to add temporary notes before opening a new
 issue. Given that our release milestones function off of issues, we believe
 tasks should have dedicated issues.
-It also gives us a way to separate the issue triage from bigger-picture, long-term work.
+Project boards also give us a way to separate the issue triage from
 bigger-picture, long-term work.
 ## Versioning
 `<major.minor.patch>`
-The code-server project follows traditional [semantic versioning](https://semver.org/), with the objective of minimizing major changes that break backward compatibility. We increment the patch level for all releases, except when the upstream Visual Studio Code project increments its minor version or we change the plugin API in a backward-compatible manner. In those cases, we increment the minor version rather than the patch level.
+The code-server project follows traditional [semantic
 versioning](https://semver.org/), with the objective of minimizing major changes
 that break backward compatibility. We increment the patch level for all
 releases, except when the upstream Visual Studio Code project increments its
 minor version or we change the plugin API in a backward-compatible manner. In
 those cases, we increment the minor version rather than the patch level.
-## Pull Requests
+## Pull requests
-Ideally, every PR should fix an issue. If it doesn't, make sure it's associated with a version milestone.
+Ideally, every PR should fix an issue. If it doesn't, make sure it's associated
 with a version milestone.
-If a PR does fix an issue, don't add it to the version milestone. Otherwise, the version milestone will have duplicate information: the issue & the PR fixing the issue.
+If a PR does fix an issue, don't add it to the version milestone. Otherwise, the
 version milestone will have duplicate information: the issue and the PR fixing
 the issue.
-### Merge Strategies
+### Merge strategies
-For most things, we recommend "Squash and Merge". If you're updating `lib/vscode`, we suggest using the "Rebase and Merge" strategy. There may be times where "Create a merge commit" makes sense as well. Use your best judgement. If you're unsure, you can always discuss in the PR with the team.
+For most things, we recommend the **squash and merge** strategy. If you're
-The code-server project follows traditional [semantic versioning](ttps://semver.org/), with the objective of minimizing major changes that break backward compatibility. We increment the patch level for all releases, except when the upstream Visual Studio Code project increments its minor version or we change the plugin API in a backward-compatible manner. In those cases, we increment the minor version rather than the patch level.
+updating `lib/vscode`, we suggest using the **rebase and merge** strategy. There
 may be times where **creating a merge commit** makes sense as well. Use your
 best judgment. If you're unsure, you can always discuss in the PR with the team.
 ### Changelog
-To save time when creating a new release for code-server, we keep a running changelog at `CHANGELOG.md`.
+To save time when creating a new release for code-server, we keep a running
 changelog at `CHANGELOG.md`.
-If either author or reviewer of a PR believe the change should be mentioned in the `CHANGELOG`, then it should be added.
+If either the author or reviewer of a PR believes the change should be mentioned
 in the changelog, then it should be added.
-If there is not a "Next Version" when you modify `CHANGELOG`, please add it using the template you see near the top of `CHANGELOG`.
+If there is not a **Next Version** when you modify `CHANGELOG.md`, please add it
 using the template you see near the top of the changelog.
-As for what you should write for your changelog item, we should asking yourself these two questions:
+When writing your changelog item, ask yourself:
 1. How do these changes affect code-server users?
-2. What actions do they need to take? (if any)
+2. What actions do they need to take (if any)?
-If you need inspiration, we suggest looking at the [Emacs changelog](https://github.com/emacs-mirror/emacs/blob/master/etc/NEWS).
+If you need inspiration, we suggest looking at the [Emacs
 changelog](https://github.com/emacs-mirror/emacs/blob/master/etc/NEWS).
-## Release
+## Releases
-### Release Manager Rotation
+With each release, we rotate the role of release manager to ensure every
-
+maintainer goes through the process. This helps us keep documentation up-to-date
-With each release, we rotate the role of "release manager" to ensure every maintainer goes through the process. This helps us keep documentation up-to-date and encourages us to continually review and improve the flow with each set of eyes.
+and encourages us to continually review and improve the flow.
 If you're the current release manager, follow these steps:
 1. Create a [release issue](../.github/ISSUE_TEMPLATE/release.md)
-2. Fill out checklist
+1. Fill out checklist
-3. After release is published, close release milestone
+1. Publish the release
 1. After release is published, close release milestone
 ### Publishing a release
-1. Run `yarn release:prep` and type in the new version i.e. 3.8.1
+1. Run `yarn release:prep` and type in the new version (e.g., `3.8.1`)
-2. GitHub actions will generate the `npm-package`, `release-packages` and `release-images` artifacts.
+1. GitHub Actions will generate the `npm-package`, `release-packages` and
-   1. You do not have to wait for these.
+   `release-images` artifacts. You do not have to wait for this step to complete
-3. Run `yarn release:github-draft` to create a GitHub draft release from the template with
+   before proceeding.
-   the updated version.
+1. Run `yarn release:github-draft` to create a GitHub draft release from the
-   1. Summarize the major changes in the release notes and link to the relevant issues.
+   template with the updated version.
-   2. Change the @ to target the version branch. Example: `v3.9.0 @ Target: v3.9.0`
+1. Summarize the major changes in the release notes and link to the relevant
-4. Wait for the artifacts in step 2 to build.
+   issues.
-5. Run `yarn release:github-assets` to download the `release-packages` artifact.
+1. Change the @ to target the version branch. Example: `v3.9.0 @ Target: v3.9.0`
-   - It will upload them to the draft release.
+1. Wait for the `npm-package`, `release-packages` and `release-images` artifacts
-6. Run some basic sanity tests on one of the released packages.
+   to build.
-   - Especially make sure the terminal works fine.
+1. Run `yarn release:github-assets` to download the `release-packages` artifact.
-7. Publish the release and merge the PR.
+   They will upload them to the draft release.
-   1. CI will automatically grab the artifacts and then:
+1. Run some basic sanity tests on one of the released packages (pay special
-      1. Publish the NPM package from `npm-package`.
+   attention to making sure the terminal works).
-      2. Publish the Docker Hub image from `release-images`.
+1. Publish the release and merge the PR. CI will automatically grab the
-8. Update the AUR package.
+   artifacts, publish the NPM package from `npm-package`, and publish the Docker
-   - Instructions on updating the AUR package are at [cdr/code-server-aur](https://github.com/cdr/code-server-aur).
+   Hub image from `release-images`.
-9. Wait for the npm package to be published.
+1. Update the AUR package. Instructions for updating the AUR package are at
   [cdr/code-server-aur](https://github.com/cdr/code-server-aur).
 1. Wait for the npm package to be published.
--- a/docs/README.md
+++ b/docs/README.md
@ -2,7 +2,8 @@
 [!["GitHub Discussions"](https://img.shields.io/badge/%20GitHub-%20Discussions-gray.svg?longCache=true&logo=github&colorB=purple)](https://github.com/cdr/code-server/discussions) [!["Join us on Slack"](https://img.shields.io/badge/join-us%20on%20slack-gray.svg?longCache=true&logo=slack&colorB=brightgreen)](https://cdr.co/join-community) [![Twitter Follow](https://img.shields.io/twitter/follow/CoderHQ?label=%40CoderHQ&style=social)](https://twitter.com/coderhq) [![codecov](https://codecov.io/gh/cdr/code-server/branch/main/graph/badge.svg?token=5iM9farjnC)](https://codecov.io/gh/cdr/code-server) [![See v3.10.2 docs](https://img.shields.io/static/v1?label=Docs&message=see%20v3.10.2%20&color=blue)](https://github.com/cdr/code-server/tree/v3.10.2/docs)
-Run [VS Code](https://github.com/Microsoft/vscode) on any machine anywhere and access it in the browser.
+Run [VS Code](https://github.com/Microsoft/vscode) on any machine anywhere and
 access it in the browser.
 ![Screenshot](./assets/screenshot.png)
@ -10,26 +11,31 @@ Run [VS Code](https://github.com/Microsoft/vscode) on any machine anywhere and a
 - Code on any device with a consistent development environment
 - Use cloud servers to speed up tests, compilations, downloads, and more
- Preserve battery life when you're on the go; all intensive tasks run on your server
+- Preserve battery life when you're on the go; all intensive tasks run on your
  server
 ## Requirements
-For a good experience, we recommend at least:
+See [requirements](requirements.md) for minimum specs, as well as instructions
 on how to set up a Google VM on which you can install code-server.
- 1 GB of RAM
+**TL;DR:** Linux machine with WebSockets enabled, 1 GB RAM, and 2 CPUs
 - 2 cores
-You can use whatever linux distribution floats your boat but in our [guide](https://coder.com/docs/code-server/v3.10.2/guide) we assume Debian on Google Cloud.
+## Getting started
-## Getting Started
+There are three ways to get started:
-There are three ways you can get started:
+1. Using the [install
   script](https://github.com/cdr/code-server/blob/main/install.sh), which
   automates most of the process. The script uses the system package manager if
   possible.
 2. Manually [installing
   code-server](https://coder.com/docs/code-server/v3.10.2/install)
 3. Using our one-click buttons and guides to [deploy code-server to a cloud
   provider](https://github.com/cdr/deploy-code-server) ⚡
-1. Using the [install script](https://github.com/cdr/code-server/blob/main/install.sh), which automates most of the process. The script uses the system package manager (if possible)
+If you use the install script, you can preview what occurs during the install
-2. Manually installing code-server; see [Installation](https://coder.com/docs/code-server/v3.10.2/install) for instructions applicable to most use cases
+process:
 3. Use our one-click buttons and guides to [deploy code-server to a popular cloud provider](https://github.com/cdr/deploy-code-server) ⚡
 If you choose to use the install script, you can preview what occurs during the install process:
 ```bash
 curl -fsSL https://code-server.dev/install.sh | sh -s -- --dry-run
@ -41,37 +47,43 @@ To install, run:
 curl -fsSL https://code-server.dev/install.sh | sh
 ```
-When done, the install script prints out instructions for running and starting code-server.
+When done, the install script prints out instructions for running and starting
 code-server.
-We also have an in-depth [setup and configuration](https://coder.com/docs/code-server/v3.10.2/guide) guide.
+We also have an in-depth [setup and
 configuration](https://coder.com/docs/code-server/v3.10.2/guide) guide.
 ### code-server --link
-We're working on a cloud platform that makes deploying and managing code-server easier.
+We're working on a cloud platform that makes deploying and managing code-server
-Consider running code-server with the beta flag `--link` if you don't want to worry about
+easier. Consider running code-server with the beta flag `--link` if you don't
 want to worry about:
 - TLS
 - Authentication
- Port Forwarding
+- Port forwarding
 ```bash
 $ code-server --link
-Proxying code-server, you can access your IDE at https://valmar-jon.cdr.co
+Proxying code-server, you can access your IDE at https://example.cdr.co
 ```
-## FAQ
+## Questions?
-See [./FAQ.md](https://coder.com/docs/code-server/v3.10.2/FAQ).
+See answers to [frequently asked
 questions](https://coder.com/docs/code-server/v3.10.2/FAQ).
 ## Want to help?
-See [CONTRIBUTING](https://coder.com/docs/code-server/v3.10.2/CONTRIBUTING) for details.
+See [Contributing](https://coder.com/docs/code-server/v3.10.2/CONTRIBUTING) for
 details.
 ## Hiring
-Interested in [working at Coder](https://coder.com/careers)? Check out [our open positions](https://coder.com/careers#openings)!
+Interested in [working at Coder](https://coder.com/careers)? Check out [our open
 positions](https://coder.com/careers#openings)!
 ## For Organizations
-Want remote development for your organization or enterprise? Visit
+Want remote development for your organization or enterprise? Visit [our
-[our website](https://coder.com) to learn more about Coder.
+website](https://coder.com) to learn more about Coder.
--- a/docs/SECURITY.md
+++ b/docs/SECURITY.md
@ -1,24 +1,30 @@
 # Security Policy
-The code-server team (and Coder, the organization) care a lot about keeping the project secure and safe for end-users.
+Coder and the code-server team want to keep the code-server project secure and safe for end-users.
 ## Tools
-We use a combination of tools to help us stay on top of vulnerabilities.
+We use the following tools to help us stay on top of vulnerability mitigation.
 - [dependabot](https://dependabot.com/)
-  - Submits pull requests to upgrade dependencies. We use dependabot's version upgrades as well as security updates.
+  - Submits pull requests to upgrade dependencies. We use dependabot's version
    upgrades as well as security updates.
 - code-scanning
  - [CodeQL](https://securitylab.github.com/tools/codeql/)
-    - Semantic code analysis engine that runs on a regular schedule (see `codeql-analysis.yml`)
+    - Semantic code analysis engine that runs on a regular schedule (see
      `codeql-analysis.yml`)
  - [trivy](https://github.com/aquasecurity/trivy)
-    - Comprehensive vulnerability scanner that runs on PRs into the default branch and scans both our container image and repository code (see `trivy-scan-repo` and `trivy-scan-image` jobs in `ci.yaml`)
+    - Comprehensive vulnerability scanner that runs on PRs into the default
      branch and scans both our container image and repository code (see
      `trivy-scan-repo` and `trivy-scan-image` jobs in `ci.yaml`)
 - [`audit-ci`](https://github.com/IBM/audit-ci)
-  - Audits npm and Yarn dependencies in CI (see "Audit for vulnerabilities" step in `ci.yaml`) on PRs into the default branch and fails CI if moderate or higher vulnerabilities(see the `audit.sh` script) are present.
+  - Audits npm and Yarn dependencies in CI (see `Audit for vulnerabilities` step
    in `ci.yaml`) on PRs into the default branch and fails CI if moderate or
    higher vulnerabilities (see the `audit.sh` script) are present.
 ## Supported Versions
-Coder sponsors development and maintenance of the code-server project. We will fix security issues within 90 days of receiving a report, and publish the fix in a subsequent release. The code-server project does not provide backports or patch releases for security issues at this time.
+Coder sponsors the development and maintenance of the code-server project. We will fix security issues within 90 days of receiving a report and publish the fix in a subsequent release. The code-server project does not provide backports or patch releases for security issues at this time.
 | Version                                               | Supported          |
 | ----------------------------------------------------- | ------------------ |
@ -26,4 +32,4 @@ Coder sponsors development and maintenance of the code-server project. We will f
 ## Reporting a Vulnerability
-To report a vulnerability, please send an email to security[@]coder.com and our security team will respond to you.
+To report a vulnerability, please send an email to security[@]coder.com, and our security team will respond to you.
--- a/docs/guide.md
+++ b/docs/guide.md
@ -2,186 +2,124 @@
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 # Setup Guide
- [1. Acquire a remote machine](#1-acquire-a-remote-machine)
+- [Expose code-server](#expose-code-server)
-  - [Requirements](#requirements)
+  - [Port forwarding via SSH](#port-forwarding-via-ssh)
-  - [Google Cloud](#google-cloud)
+  - [Using Let's Encrypt with Caddy](#using-lets-encrypt-with-caddy)
- [2. Install code-server](#2-install-code-server)
+  - [Using Let's Encrypt with NGINX](#using-lets-encrypt-with-nginx)
- [3. Expose code-server](#3-expose-code-server)
+  - [Using a self-signed certificate](#using-a-self-signed-certificate)
-  - [SSH forwarding](#ssh-forwarding)
+- [External authentication](#external-authentication)
-  - [Let's Encrypt](#lets-encrypt)
+- [HTTPS](#https)
    - [NGINX](#nginx)
  - [Self Signed Certificate](#self-signed-certificate)
-  - [Change the password?](#change-the-password)
+  - [Using a subdomain](#using-a-subdomain)
-  - [How do I securely access development web services?](#how-do-i-securely-access-development-web-services)
+  - [Using a subpath](#using-a-subpath)
  - [Stripping `/proxy/<port>` from the request path](#stripping-proxyport-from-the-request-path)
  - [Proxying to create a React app](#proxying-to-create-a-react-app)
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
-This guide demonstrates how to setup and use `code-server`.
+This article will walk you through exposing code-server securely once you've
-To reiterate, `code-server` lets you run VS Code on a remote server and then access it via a browser.
+completed the [installation process](install.md).
-Further docs are at:
+## Expose code-server
- [README](../README.md) for a general overview
+**Never** expose code-server directly to the internet without some form of
- [INSTALL](../docs/install.md) for installation
+authentication and encryption, otherwise someone can take over your machine via
- [FAQ](./FAQ.md) for common questions.
+the terminal.
 - [CONTRIBUTING](../docs/CONTRIBUTING.md) for development docs
-We highly recommend reading the [FAQ](./FAQ.md) on the [Differences compared to VS Code](./FAQ.md#differences-compared-to-vs-code) before beginning.
+By default, code-server uses password authentication. As such, you must copy the
 password from code-server's config file to log in. To avoid exposing itself
 unnecessarily, code-server listens on `localhost`; this practice is fine for
 testing, but it doesn't work if you want to access code-server from a different
 machine.
-We'll walk you through acquiring a remote machine to run `code-server` on
+> **Rate limits:** code-server rate limits password authentication attempts to
-and then exposing `code-server` so you can securely access it.
+> two per minute and twelve per hour.
-## 1. Acquire a remote machine
+There are several approaches to operating and exposing code-server securely:
-First, you need a machine to run `code-server` on. You can use a physical
+- Port forwarding via SSH
-machine you have lying around or use a VM on GCP/AWS.
+- Using Let's Encrypt with Caddy
 - Using Let's Encrypt with NGINX
 - Using a self-signed certificate
-### Requirements
+### Port forwarding via SSH
-For a good experience, we recommend at least:
+We highly recommend using [port forwarding via
 SSH](https://help.ubuntu.com/community/SSH/OpenSSH/PortForwarding) to access
 code-server. If you have an SSH server on your remote machine, this approach
 doesn't required additional setup.
- 1 GB of RAM
+The downside to SSH forwarding, however, is that you can't access code-server
- 2 cores
+when using machines without SSH clients (such as iPads). If this applies to you,
 we recommend using another method, such as [Let's Encrypt](#let-encrypt) instead.
-You can use whatever linux distribution floats your boat but in this guide we assume Debian on Google Cloud.
+> To work properly, your environment should have WebSockets enabled, which
 > code-server uses to communicate between the browser and server.
-In order to work properly, your environment should have WebSockets enabled, which code-server uses to communicate between the browser and server
+1. SSH into your instance and edit the code-server config file to disable
   password authentication:
-### Google Cloud
+   ```console
   # Replaces "auth: password" with "auth: none" in the code-server config.
   sed -i.bak 's/auth: password/auth: none/' ~/.config/code-server/config.yaml
   ```
-For demonstration purposes, this guide assumes you're using a VM on GCP but you should be
+2. Restart code-server:
 able to easily use any machine or VM provider.
-You can sign up at https://console.cloud.google.com/getting-started. You'll get a 12 month \$300
+   ```console
-free trial.
+   sudo systemctl restart code-server@$USER
   ```
-Once you've signed up and created a GCP project, create a new Compute Engine VM Instance.
+3. Forward local port `8080` to `127.0.0.1:8080` on the remote instance by running the following command on your local machine:
-1. Navigate to `Compute Engine -> VM Instances` on the sidebar.
+   ```console
-2. Now click `Create Instance` to create a new instance.
+   # -N disables executing a remote shell
-3. Name it whatever you want.
+   ssh -N -L 8080:127.0.0.1:8080 [user]@<instance-ip>
-4. Choose the region closest to you based on [gcping.com](http://www.gcping.com).
+   ```
 5. Any zone is fine.
 6. We'd recommend a `E2` series instance from the General-purpose family.
   - Change the type to custom and set at least 2 cores and 2 GB of ram.
   - Add more vCPUs and memory as you prefer, you can edit after creating the instance as well.
   - https://cloud.google.com/compute/docs/machine-types#general_purpose
 7. We highly recommend switching the persistent disk to an SSD of at least 32 GB.
   - Click `Change` under `Boot Disk` and change the type to `SSD Persistent Disk` and the size
     to `32`.
   - You can always grow your disk later.
 8. Navigate to `Networking -> Network interfaces` and edit the existing interface
   to use a static external IP.
   - Click done to save network interface changes.
 9. If you do not have a [project wide SSH key](https://cloud.google.com/compute/docs/instances/adding-removing-ssh-keys#project-wide), navigate to `Security -> SSH Keys` and add your public key there.
 10. Click create!
-Remember, you can shutdown your server when not in use to lower costs.
+4. At this point, you can access code-server by pointing your web browser to `http://127.0.0.1:8080`.
-We highly recommend learning to use the [`gcloud`](https://cloud.google.com/sdk/gcloud) cli
+5. If you'd like to make the port forwarding via SSH persistent, we recommend
-to avoid the slow dashboard.
+   using [mutagen](https://mutagen.io/documentation/introduction/installation)
   to do so. Once you've installed mutagen, you can port forward as follows:
-## 2. Install code-server
+   ```console
   # This is the same as the above SSH command, but it runs in the background
   # continuously. Be sure to add `mutagen daemon start` to your ~/.bashrc to
   # start the mutagen daemon when you open a shell.
-We have a [script](../install.sh) to install `code-server` for Linux, macOS and FreeBSD.
+   mutagen forward create --name=code-server tcp:127.0.0.1:8080 < instance-ip > :tcp:127.0.0.1:8080
   ```
-It tries to use the system package manager if possible.
+6. Optional, but highly recommended: add the following to `~/.ssh/config` so
   that you can detect bricked SSH connections:
-First run to print out the install process:
+   ```bash
   Host *
   ServerAliveInterval 5
   ExitOnForwardFailure yes
   ```
-```bash
+> You can [forward your
-curl -fsSL https://code-server.dev/install.sh | sh -s -- --dry-run
+> SSH](https://developer.github.com/v3/guides/using-ssh-agent-forwarding/) and
-```
+> [GPG agent](https://wiki.gnupg.org/AgentForwarding) to the instance to
 > securely access GitHub and sign commits without having to copy your keys.
-Now to actually install:
+### Using Let's Encrypt with Caddy
-```bash
+Using [Let's Encrypt](https://letsencrypt.org) is an option if you want to
-curl -fsSL https://code-server.dev/install.sh | sh
+access code-server on an iPad or do not want to use SSH port forwarding.
 ```
-The install script will print out how to run and start using `code-server`.
+1. This option requires that the remote machine be exposed to the internet. Make sure that your instance allows HTTP/HTTP traffic.
-Docs on the install script, manual installation and docker image are at [./install.md](./install.md).
+1. You'll need a domain name (if you don't have one, you can purchase one from
   [Google Domains](https://domains.google.com) or the domain service of your
   choice)). Once you have a domain name, add an A record to your domain that contains your
   instance's IP address.
-## 3. Expose code-server
+1. Install [Caddy](https://caddyserver.com/docs/download#debian-ubuntu-raspbian):
-**Never**, **ever** expose `code-server` directly to the internet without some form of authentication
+```console
 and encryption as someone can completely takeover your machine with the terminal.
 By default, `code-server` will enable password authentication which will require you to copy the
 password from the`code-server`config file to login. It will listen on`localhost` to avoid exposing
 itself to the world. This is fine for testing but will not work if you want to access `code-server`
 from a different machine.
 There are several approaches to securely operating and exposing `code-server`.
 **tip**: You can list the full set of `code-server` options with `code-server --help`
 ### SSH forwarding
 We highly recommend this approach for not requiring any additional setup, you just need an
 SSH server on your remote machine. The downside is you won't be able to access `code-server`
 on any machine without an SSH client like on iPad. If that's important to you, skip to [Let's Encrypt](#lets-encrypt).
 First, ssh into your instance and edit your `code-server` config file to disable password authentication.
 ```bash
 # Replaces "auth: password" with "auth: none" in the code-server config.
 sed -i.bak 's/auth: password/auth: none/' ~/.config/code-server/config.yaml
 ```
 Restart `code-server` with (assuming you followed the guide):
 ```bash
 sudo systemctl restart code-server@$USER
 ```
 Now forward local port 8080 to `127.0.0.1:8080` on the remote instance by running the following command on your local machine.
 Recommended reading: https://help.ubuntu.com/community/SSH/OpenSSH/PortForwarding.
 ```bash
 # -N disables executing a remote shell
 ssh -N -L 8080:127.0.0.1:8080 [user]@<instance-ip>
 ```
 Now if you access http://127.0.0.1:8080 locally, you should see `code-server`!
 If you want to make the SSH port forwarding persistent we recommend using
 [mutagen](https://mutagen.io/documentation/introduction/installation).
 ```
 # Same as the above SSH command but runs in the background continuously.
 # Add `mutagen daemon start` to your ~/.bashrc to start the mutagen daemon when you open a shell.
 mutagen forward create --name=code-server tcp:127.0.0.1:8080 <instance-ip>:tcp:127.0.0.1:8080
 ```
 We also recommend adding the following lines to your `~/.ssh/config` to quickly detect bricked SSH connections:
 ```bash
 Host *
 ServerAliveInterval 5
 ExitOnForwardFailure yes
 ```
 You can also forward your SSH and GPG agent to the instance to securely access GitHub
 and sign commits without copying your keys.
 1. https://developer.github.com/v3/guides/using-ssh-agent-forwarding/
 2. https://wiki.gnupg.org/AgentForwarding
 ### Let's Encrypt
 [Let's Encrypt](https://letsencrypt.org) is a great option if you want to access `code-server` on an iPad
 or do not want to use SSH forwarding. This does require that the remote machine be exposed to the internet.
 Assuming you have been following the guide, edit your instance and checkmark the allow HTTP/HTTPS traffic options.
 1. You'll need to buy a domain name. We recommend [Google Domains](https://domains.google.com).
 2. Add an A record to your domain with your instance's IP.
 3. Install Caddy https://caddyserver.com/docs/download#debian-ubuntu-raspbian.
 ```bash
 sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
 curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/cfg/gpg/gpg.155B6D79CA56EA34.key' | sudo apt-key add -
 curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/cfg/setup/config.deb.txt?distro=debian&version=any-version' | sudo tee -a /etc/apt/sources.list.d/caddy-stable.list
@ -189,51 +127,55 @@ sudo apt update
 sudo apt install caddy
 ```
-4. Replace `/etc/caddy/Caddyfile` with sudo to look like this:
+1. Replace `/etc/caddy/Caddyfile` using `sudo` so that the file looks like this:
-```
+   ```text
-mydomain.com
+   mydomain.com
-reverse_proxy 127.0.0.1:8080
+   reverse_proxy 127.0.0.1:8080
-```
+   ```
-If you want to serve `code-server` from a sub-path, below is sample configuration for Caddy:
+   If you want to serve code-server from a sub-path, you can do so as follows:
-```
+   ```text
-mydomain.com/code/* {
+   mydomain.com/code/* {
     uri strip_prefix /code
     reverse_proxy 127.0.0.1:8080
-}
+      }
-```
+   ```
-Remember to replace `mydomain.com` with your domain name!
+   Remember to replace `mydomain.com` with your domain name!
-5. Reload Caddy with:
+1. Reload Caddy:
-```bash
+   ```console
-sudo systemctl reload caddy
+   sudo systemctl reload caddy
-```
+   ```
-Visit `https://<your-domain-name>` to access `code-server`. Congratulations!
+At this point, you should be able to access code-server via
 `https://mydomain.com`.
-In a future release we plan to integrate Let's Encrypt directly with `code-server` to avoid
+### Using Let's Encrypt with NGINX
 the dependency on Caddy.
-#### NGINX
+1. This option requires that the remote machine be exposed to the internet. Make sure that your instance allows HTTP/HTTP traffic.
-If you prefer to use NGINX instead of Caddy then please follow steps 1-2 above and then:
+1. You'll need a domain name (if you don't have one, you can purchase one from
   [Google Domains](https://domains.google.com) or the domain service of your
   choice)). Once you have a domain name, add an A record to your domain that contains your
   instance's IP address.
-3. Install `nginx`:
+1. Install NGINX:
-```bash
+   ```bash
-sudo apt update
+   sudo apt update
-sudo apt install -y nginx certbot python3-certbot-nginx
+   sudo apt install -y nginx certbot python3-certbot-nginx
-```
+   ```
-4. Put the following config into `/etc/nginx/sites-available/code-server` with sudo:
+1. Update `/etc/nginx/sites-available/code-server` using sudo with the following
   configuration:
-```nginx
+   ```text
-server {
+   server {
       listen 80;
       listen [::]:80;
       server_name mydomain.com;
@ -245,77 +187,164 @@ server {
         proxy_set_header Connection upgrade;
         proxy_set_header Accept-Encoding gzip;
       }
-}
+   }
-```
+   ```
-Remember to replace `mydomain.com` with your domain name!
+   Be sure to replace `mydomain.com` with your domain name!
-5. Enable the config:
+1. Enable the config:
-```bash
+   ```console
-sudo ln -s ../sites-available/code-server /etc/nginx/sites-enabled/code-server
+   sudo ln -s ../sites-available/code-server /etc/nginx/sites-enabled/code-server
-sudo certbot --non-interactive --redirect --agree-tos --nginx -d mydomain.com -m me@example.com
+   sudo certbot --non-interactive --redirect --agree-tos --nginx -d mydomain.com -m me@example.com
-```
+   ```
-Make sure to substitute `me@example.com` with your actual email.
+   Be sure to replace `me@example.com` with your actual email.
-Visit `https://<your-domain-name>` to access `code-server`. Congratulations!
+At this point, you should be able to access code-server via
 `https://mydomain.com`.
 ### Using a self-signed certificate
 > Self signed certificates do not work with iPad; see [./ipad.md](./ipad.md) for
 > more information.
 Before proceeding, we recommend familiarizing yourself with the [risks of
 self-signing a certificate for
 SSL](https://security.stackexchange.com/questions/8110).
 We recommend self-signed certificates as a last resort, since self-signed
 certificates do not work with iPads and may cause unexpected issues with
 code-server. You should only proceed with this option if:
 - You do not want to buy a domain or you cannot expose the remote machine to
  the internet
 - You do not want to use port forwarding via SSH
 To use a self-signed certificate:
 1. This option requires that the remote machine be exposed to the internet. Make
   sure that your instance allows HTTP/HTTP traffic.
 1. SSH into your instance and edit your code-server config file to use a
   randomly generated self-signed certificate:
   ```console
   # Replaces "cert: false" with "cert: true" in the code-server config.
   sed -i.bak 's/cert: false/cert: true/' ~/.config/code-server/config.yaml
   # Replaces "bind-addr: 127.0.0.1:8080" with "bind-addr: 0.0.0.0:443" in the code-server config.
   sed -i.bak 's/bind-addr: 127.0.0.1:8080/bind-addr: 0.0.0.0:443/' ~/.config/code-server/config.yaml
   # Allows code-server to listen on port 443.
   sudo setcap cap_net_bind_service=+ep /usr/lib/code-server/lib/node
   ```
 1. Restart code-server:
   ```console
   sudo systemctl restart code-server@$USER
   ```
 At this point, you should be able to access code-server via
 `https://<your-instance-ip>`.
 If you'd like to avoid the warnings displayed by code-server when using a
 self-signed certificate, you can use [mkcert](https://mkcert.dev) to create a
 self-signed certificate that's trusted by your operating system, then pass the
 certificate to code-server via the `cert` and `cert-key` config fields.
 ## External authentication
 If you want to use external authentication mechanism (e.g., Sign in with
 Google), you can do this with a reverse proxy such as:
 - [Pomerium](https://www.pomerium.io/guides/code-server.html)
 - [oauth2_proxy](https://github.com/pusher/oauth2_proxy)
 - [Cloudflare Access](https://teams.cloudflare.com/access)
 ## HTTPS
 For HTTPS, you can use a self-signed certificate by:
 - Passing in `--cert`
 - Passing in an existing certificate by providing the path to `--cert` and the
  path to the key with `--cert-key`
 The self signed certificate will be generated to
 `~/.local/share/code-server/self-signed.crt`.
 If you pass a certificate to code-server, it will respond to HTTPS requests and
 redirect all HTTP requests to HTTPS.
 > You can use [Let's Encrypt](https://letsencrypt.org/) to get a TLS certificate
 > for free.
 Note: if you set `proxy_set_header Host $host;` in your reverse proxy config, it will change the address displayed in the green section of code-server in the bottom left to show the correct address.
 ### Self Signed Certificate
-**note:** Self signed certificates do not work with iPad normally. See [./ipad.md](./ipad.md) for details.
+If you're working on a web service and want to access it locally, code-server
 can proxy to any port using either a subdomain or a subpath, allowing you to
 securely access these services using code-server's built-in authentication.
-Recommended reading: https://security.stackexchange.com/a/8112.
+### Using a subdomain
-We recommend this as a last resort because self signed certificates do not work with iPads and can
+You will need a DNS entry that points to your server for each port you want to
-cause other bizarre issues. Not to mention all the warnings when you access `code-server`.
+access. You can either set up a wildcard DNS entry for `*.<domain>` if your
-Only use this if:
+domain name registrar supports it, or you can create one for every port you want
 to access (`3000.<domain>`, `8080.<domain>`, etc).
-1. You do not want to buy a domain or you cannot expose the remote machine to the internet.
+You should also set up TLS certificates for these subdomains, either using a
-2. You do not want to use SSH forwarding.
+wildcard certificate for `*.<domain>` or individual certificates for each port.
-ssh into your instance and edit your code-server config file to use a randomly generated self signed certificate:
+To set your domain, start code-server with the `--proxy-domain` flag:
-```bash
+```console
-# Replaces "cert: false" with "cert: true" in the code-server config.
+code-server --proxy-domain <domain>
 sed -i.bak 's/cert: false/cert: true/' ~/.config/code-server/config.yaml
 # Replaces "bind-addr: 127.0.0.1:8080" with "bind-addr: 0.0.0.0:443" in the code-server config.
 sed -i.bak 's/bind-addr: 127.0.0.1:8080/bind-addr: 0.0.0.0:443/' ~/.config/code-server/config.yaml
 # Allows code-server to listen on port 443.
 sudo setcap cap_net_bind_service=+ep /usr/lib/code-server/lib/node
 ```
-Assuming you have been following the guide, restart `code-server` with:
+Now you can browse to `<port>.<domain>`. Note that this uses the host header, so
 ensure your reverse proxy (if you're using one) forwards that information.
-```bash
+### Using a subpath
-sudo systemctl restart code-server@$USER
+
 Simply browse to `/proxy/<port>/`.
 ### Stripping `/proxy/<port>` from the request path
 You may notice that the code-server proxy strips `/proxy/<port>` from the
 request path.
 HTTP servers should use relative URLs to avoid the need to be coupled to the
 absolute path at which they are served. This means you must [use trailing
 slashes on all paths with
 subpaths](https://blog.cdivilly.com/2019/02/28/uri-trailing-slashes).
 This reasoning is why the default behavior is to strip `/proxy/<port>` from the
 base path. If your application uses relative URLs and does not assume the
 absolute path at which it is being served, it will just work no matter what port
 you decide to serve it off or if you put it in behind code-server or any other
 proxy.
 However, some prefer the cleaner aesthetic of no trailing slashes. Omitting the
 trailing slashes couples you to the base path, since you cannot use relative
 redirects correctly anymore. If you're okay with this tradeoff, use `/absproxy`
 instead and the path will be passed as is (e.g., `/absproxy/3000/my-app-path`).
 ### Proxying to create a React app
 You must use `/absproxy/<port>` with `create-react-app` (see
 [#2565](https://github.com/cdr/code-server/issues/2565) and
 [#2222](https://github.com/cdr/code-server/issues/2222) for more information).
 You will need to inform `create-react-app` of the path at which you are serving
 via `$PUBLIC_URL` and webpack via `$WDS_SOCKET_PATH`:
 ```sh
 PUBLIC_URL=/absproxy/3000 \
  WDS_SOCKET_PATH=$PUBLIC_URL/sockjs-node \
  BROWSER=none yarn start
 ```
-Edit your instance and checkmark the allow HTTPS traffic option.
+You should then be able to visit `https://my-code-server-address.io/absproxy/3000` to see your app exposed through
 code-server!
-Visit `https://<your-instance-ip>` to access `code-server`.
+> We highly recommend using the subdomain approach instead to avoid this class of issue.
 You'll get a warning when accessing but if you click through you should be good.
 To avoid the warnings, you can use [mkcert](https://mkcert.dev) to create a self signed certificate
 trusted by your OS and then pass it into `code-server` via the `cert` and `cert-key` config
 fields.
 ### Change the password?
 Edit the `password` field in the `code-server` config file at `~/.config/code-server/config.yaml`
 and then restart `code-server` with:
 ```bash
 sudo systemctl restart code-server@$USER
 ```
 Alternatively, you can specify the SHA-256 of your password at the `hashed-password` field in the config file.
 The `hashed-password` field takes precedence over `password`.
 ### How do I securely access development web services?
 If you're working on a web service and want to access it locally, `code-server` can proxy it for you.
 See the [FAQ](./FAQ.md#how-do-i-securely-access-web-services).
--- a/docs/install.md
+++ b/docs/install.md
@ -2,96 +2,161 @@
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 # Install
 - [Upgrading](#upgrading)
 - [install.sh](#installsh)
-  - [Flags](#flags)
+  - [Detection reference](#detection-reference)
-  - [Detection Reference](#detection-reference)
+- [yarn, npm](#yarn-npm)
 - [Standalone releases](#standalone-releases)
 - [Debian, Ubuntu](#debian-ubuntu)
 - [Fedora, CentOS, RHEL, SUSE](#fedora-centos-rhel-suse)
 - [Arch Linux](#arch-linux)
 - [Termux](#termux)
 - [Raspberry Pi](#raspberry-pi)
 - [yarn, npm](#yarn-npm)
 - [macOS](#macos)
 - [Standalone Releases](#standalone-releases)
 - [Docker](#docker)
- [helm](#helm)
+- [Helm](#helm)
- [Cloud Providers](#cloud-providers)
+- [Raspberry Pi](#raspberry-pi)
- [Troubleshooting Node Issues](#troubleshooting-node-issues)
+- [Termux](#termux)
 - [Cloud providers](#cloud-providers)
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
-This document demonstrates how to install `code-server` on
+This document demonstrates how to install `code-server` on various distros and
-various distros and operating systems.
+operating systems.
 ## Upgrading
 When upgrading you can just install the new version over the old one. code-server
 maintains all user data in `~/.local/share/code-server` so that it is preserved in between
 installations.
 ## install.sh
-We have a [script](../install.sh) to install code-server for Linux, macOS and FreeBSD.
+The easiest way to install code-server is to use our [install
 script](../install.sh) for Linux, macOS and FreeBSD. The install script
 [attempts to use the system package manager](#detection-reference) if possible.
-It tries to use the system package manager if possible.
+You can preview what occurs during the install process:
 First run to print out the install process:
 ```bash
 curl -fsSL https://code-server.dev/install.sh | sh -s -- --dry-run
 ```
-Now to actually install:
+To install, run:
 ```bash
 curl -fsSL https://code-server.dev/install.sh | sh
 ```
-The script will print out how to run and start using code-server.
+You can modify the installation process by including one or more of the
 following flags:
-If you believe an install script used with `curl | sh` is insecure, please give
+- `--dry-run`: echo the commands for the install process without running them.
-[this wonderful blogpost](https://sandstorm.io/news/2015-09-24-is-curl-bash-insecure-pgp-verified-install) by
+- `--method`: choose the installation method.
-[sandstorm.io](https://sandstorm.io) a read.
+  - `--method=detect`: detect the package manager but fallback to
    `--method=standalone`.
  - `--method=standalone`: install a standalone release archive into `~/.local`.
 - `--prefix=/usr/local`: install a standalone release archive system-wide.
 - `--version=X.X.X`: install version `X.X.X` instead of latest version.
 - `--help`: see usage docs.
-If you'd still prefer manual installation despite the below [detection reference](#detection-reference) and `--dry-run`
+When done, the install script prints out instructions for running and starting
-then continue on for docs on manual installation. The [`install.sh`](../install.sh) script runs the _exact_ same
+code-server.
 commands presented in the rest of this document.
-### Flags
+> If you're concerned about the install script's use of `curl | sh` and the
 > security implications, please see [this blog
 > post](https://sandstorm.io/news/2015-09-24-is-curl-bash-insecure-pgp-verified-install)
 > by [sandstorm.io](https://sandstorm.io).
- `--dry-run` to echo the commands for the install process without running them.
+If you prefer to install code-server manually, despite the [detection
- `--method` to choose the installation method.
+references](#detection-reference) and `--dry-run` feature, then continue on for
-  - `--method=detect` to detect the package manager but fallback to `--method=standalone`.
+information on how to do this. The [`install.sh`](../install.sh) script runs the
-  - `--method=standalone` to install a standalone release archive into `~/.local`.
+_exact_ same commands presented in the rest of this document.
 - `--prefix=/usr/local` to install a standalone release archive system wide.
 - `--version=X.X.X` to install version `X.X.X` instead of latest.
 - `--help` to see full usage docs.
-### Detection Reference
+### Detection reference
- For Debian and Ubuntu it will install the latest deb package.
+- For Debian and Ubuntu, code-server will install the latest deb package.
- For Fedora, CentOS, RHEL and openSUSE it will install the latest rpm package.
+- For Fedora, CentOS, RHEL and openSUSE, code-server will install the latest RPM
- For Arch Linux it will install the AUR package.
+  package.
- For any unrecognized Linux operating system it will install the latest standalone release into `~/.local`.
+- For Arch Linux, code-server will install the AUR package.
 - For any unrecognized Linux operating system, code-server will install the
  latest standalone release into `~/.local`.
-  - Add `~/.local/bin` to your `$PATH` to run code-server.
+  - Ensure that you add `~/.local/bin` to your `$PATH` to run code-server.
- For macOS it will install the Homebrew package.
+- For macOS, code-server will install the Homebrew package (if you don't have
  Homebrew installed, code-server will install the latest standalone release
  into `~/.local`).
-  - If Homebrew is not installed it will install the latest standalone release into `~/.local`.
+  - Ensure that you add `~/.local/bin` to your `$PATH` to run code-server.
  - Add `~/.local/bin` to your `$PATH` to run code-server.
- For FreeBSD, it will install the [npm package](#yarn-npm) with `yarn` or `npm`.
+- For FreeBSD, code-server will install the [npm package](#yarn-npm) with `yarn`
  or `npm`.
- If ran on an architecture with no releases, it will install the [npm package](#yarn-npm) with `yarn` or `npm`.
+- If you're installing code-server onto architecture with no releases,
-  - We only have releases for amd64 and arm64 presently.
+  code-server will install the [npm package](#yarn-npm) with `yarn` or `npm`
-  - The [npm package](#yarn-npm) builds the native modules on postinstall.
+  - We currently offer releases for amd64 and arm64.
  - The [npm package](#yarn-npm) builds the native modules on post-install.
 ## yarn, npm
 We recommend installing with `yarn` or `npm` when:
 1. You aren't using a machine with `amd64` or `arm64`.
 2. You're on Linux with `glibc` < v2.17, `glibcxx` < v3.4.18 on `amd64`, `glibc`
   < v2.23, or `glibcxx` < v3.4.21 on `arm64`.
 3. You're running Alpine Linux or are using a non-glibc libc. See
   [#1430](https://github.com/cdr/code-server/issues/1430#issuecomment-629883198)
   for more information.
 Installing code-server with `yarn` or `npm` builds native modules on install.
 This process requires C dependencies; see our guide on [installing these
 dependencies][./npm.md](./npm.md) for more information.
 You must have Node.js v12 (or later) installed. See
 [#1633](https://github.com/cdr/code-server/issues/1633).
 To install:
 ```bash
 yarn global add code-server
 # Or: npm install -g code-server
 code-server
 # Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml
 ```
 ## Standalone releases
 We publish self-contained `.tar.gz` archives for every release on
 [GitHub](https://github.com/cdr/code-server/releases). The archives bundle the
 node binary and node modules.
 We create the standalone releases using the [npm package](#yarn-npm), and we
 then create the remaining releases using the standalone version.
 The only requirement to use the standalone release is `glibc` >= 2.17 and
 `glibcxx` >= v3.4.18 on Linux (for macOS, there is no minimum system
 requirement).
 To use a standalone release:
 1. Download the latest release archive for your system from
   [GitHub](https://github.com/cdr/code-server/releases).
 2. Unpack the release.
 3. Run code-server by executing `./bin/code-server`.
 You can add `./bin/code-server` to your `$PATH` so that you can execute
 `code-server` without providing full path each time.
 Here is a sample script for installing and using a standalone code-server
 release on Linux:
 ```bash
 mkdir -p ~/.local/lib ~/.local/bin
 curl -fL https://github.com/cdr/code-server/releases/download/v$VERSION/code-server-$VERSION-linux-amd64.tar.gz \
  | tar -C ~/.local/lib -xz
 mv ~/.local/lib/code-server-$VERSION-linux-amd64 ~/.local/lib/code-server-$VERSION
 ln -s ~/.local/lib/code-server-$VERSION/bin/code-server ~/.local/bin/code-server
 PATH="~/.local/bin:$PATH"
 code-server
 # Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml
 ```
 ## Debian, Ubuntu
-NOTE: The standalone arm64 .deb does not support Ubuntu <16.04.
+> The standalone arm64 .deb does not support Ubuntu 16.04 or earlier. Please
-Please upgrade or [build with yarn](#yarn-npm).
+> upgrade or [build with yarn](#yarn-npm).
 ```bash
 curl -fOL https://github.com/cdr/code-server/releases/download/v$VERSION/code-server_$VERSION_amd64.deb
@ -102,8 +167,8 @@ sudo systemctl enable --now code-server@$USER
 ## Fedora, CentOS, RHEL, SUSE
-NOTE: The standalone arm64 .rpm does not support CentOS 7.
+> The standalone arm64 .rpm does not support CentOS 7. Please upgrade or [build
-Please upgrade or [build with yarn](#yarn-npm).
+> with yarn](#yarn-npm).
 ```bash
 curl -fOL https://github.com/cdr/code-server/releases/download/v$VERSION/code-server-$VERSION-amd64.rpm
@ -115,14 +180,14 @@ sudo systemctl enable --now code-server@$USER
 ## Arch Linux
 ```bash
-# Installs code-server from the AUR using yay.
+# Install code-server from the AUR using yay.
 yay -S code-server
 sudo systemctl enable --now code-server@$USER
 # Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml
 ```
 ```bash
-# Installs code-server from the AUR with plain makepkg.
+# Install code-server from the AUR with plain makepkg.
 git clone https://aur.archlinux.org/code-server.git
 cd code-server
 makepkg -si
@ -130,34 +195,6 @@ sudo systemctl enable --now code-server@$USER
 # Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml
 ```
 ## Termux
 Please see "Installation" in the [Termux docs](./termux.md#installation)
 ## Raspberry Pi
 If you're running a Raspberry Pi, we recommend install code-server with `yarn` or `npm`. See [yarn-npm](#yarn-npm).
 ## yarn, npm
 We recommend installing with `yarn` or `npm` when:
 1. You aren't on `amd64` or `arm64`.
 2. If you're on Linux with glibc < v2.17 or glibcxx < v3.4.18 on amd64, or glibc < v2.23 or glibcxx < v3.4.21 on arm64.
 3. You're running Alpine Linux, or are using a non-glibc libc. See [#1430](https://github.com/cdr/code-server/issues/1430#issuecomment-629883198)
 **note:** Installing via `yarn` or `npm` builds native modules on install and so requires C dependencies.
 See [./npm.md](./npm.md) for installing these dependencies.
 You will need at least node v12 installed. See [#1633](https://github.com/cdr/code-server/issues/1633).
 ```bash
 yarn global add code-server
 # Or: npm install -g code-server
 code-server
 # Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml
 ```
 ## macOS
 ```bash
@ -166,34 +203,6 @@ brew services start code-server
 # Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml
 ```
 ## Standalone Releases
 We publish self contained `.tar.gz` archives for every release on [github](https://github.com/cdr/code-server/releases).
 They bundle the node binary and `node_modules`.
 These are created from the [npm package](#yarn-npm) and the rest of the releases are created from these.
 Only requirement is glibc >= 2.17 && glibcxx >= v3.4.18 on Linux and for macOS there is no minimum system requirement.
 1. Download the latest release archive for your system from [github](https://github.com/cdr/code-server/releases).
 2. Unpack the release.
 3. You can run code-server by executing `./bin/code-server`.
 You can add the code-server `bin` directory to your `$PATH` to easily execute `code-server`
 without the full path every time.
 Here is an example script for installing and using a standalone `code-server` release on Linux:
 ```bash
 mkdir -p ~/.local/lib ~/.local/bin
 curl -fL https://github.com/cdr/code-server/releases/download/v$VERSION/code-server-$VERSION-linux-amd64.tar.gz \
  | tar -C ~/.local/lib -xz
 mv ~/.local/lib/code-server-$VERSION-linux-amd64 ~/.local/lib/code-server-$VERSION
 ln -s ~/.local/lib/code-server-$VERSION/bin/code-server ~/.local/bin/code-server
 PATH="~/.local/bin:$PATH"
 code-server
 # Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml
 ```
 ## Docker
 ```bash
@ -214,33 +223,26 @@ docker run -it --name code-server -p 127.0.0.1:8080:8080 \
  codercom/code-server:latest
 ```
-Our official image supports `amd64` and `arm64`.
+Our official image supports `amd64` and `arm64`. For `arm32` support, you can
 use a [community-maintained code-server
 alternative](https://hub.docker.com/r/linuxserver/code-server).
-For `arm32` support there is a popular community maintained alternative:
+## Helm
-[https://hub.docker.com/r/linuxserver/code-server](https://hub.docker.com/r/linuxserver/code-server)
+You can install code-server via [Helm](../ci/helm-chart/README.md).
-## helm
+## Raspberry Pi
-See [the chart](../ci/helm-chart).
+We recommend installing code-server onto Raspberry Pi with [`yarn` or
 `npm`](#yarn-npm).
-## Cloud Providers
+## Termux
-We maintain one-click apps and install scripts for different cloud providers such as DigitalOcean, Railway, Heroku, Azure, etc. Check out the repository:
+Please see code-server's [Termux docs](./termux.md#installation) for more
 information.
-[https://github.com/cdr/deploy-code-server](https://github.com/cdr/deploy-code-server)
+## Cloud providers
-## Troubleshooting Node Issues
+We maintain [one-click apps and install scripts for cloud
-
+providers](https://github.com/cdr/deploy-code-server) such as DigitalOcean,
-Occassionally, you may run into issues with node.
+Railway, Heroku, and Azure.
 If you install code-server with `yarn`/`npm` and upgrade your node version, you may need to reinstall code-server to recompile native modules. Sometimes you can get around this by `cd`'ing into the `lib/vscode` directory under code-server and running `npm rebuild` to recompile those native modules.
 An example of this might look like:
 1. You installed code-server using `brew install code-server`
 2. You `cd` into the directory `cd /usr/local/Cellar/code-server/<version>/libexec/lib/vscode/`
 3. You recompile native modules by running `npm rebuild`
 4. You restart code-server
 If you get stuck or need help, post on our [GitHub Discussions page](https://github.com/cdr/code-server/discussions).
--- a/docs/ipad.md
+++ b/docs/ipad.md
@ -2,162 +2,200 @@
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 # iPad
- [Known Issues](#known-issues)
+- [Using the code-server progressive web app (PWA)](#using-the-code-server-progressive-web-app-pwa)
- [How to install PWA](#how-to-install-pwa)
+- [Access code-server with a self-signed certificate on an iPad](#access-code-server-with-a-self-signed-certificate-on-an-ipad)
- [How to access code-server with a self signed certificate on iPad?](#how-to-access-code-server-with-a-self-signed-certificate-on-ipad)
+  - [Certificate requirements](#certificate-requirements)
-  - [Servediter iPad App](#servediter-ipad-app)
+  - [Sharing a self-signed certificate with an iPad](#sharing-a-self-signed-certificate-with-an-ipad)
- [Raspberry Pi USB-C Network](#raspberry-pi-usb-c-network)
+- [Access code-server using Servediter](#access-code-server-using-servediter)
- [Ctrl C Workaround](#ctrl-c-workaround)
+- [Raspberry Pi USB-C network](#raspberry-pi-usb-c-network)
 - [Recommendations](#recommendations)
- [By 2022 iPad coding more desirable on Arm Macs](#by-2022-ipad-coding-more-desirable-on-arm-macs)
+- [Known issues](#known-issues)
  - [Workaround for issue with `ctrl+c` not stopping a running process in the terminal](#workaround-for-issue-with-ctrlc-not-stopping-a-running-process-in-the-terminal)
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
-## Known Issues
+Once you've installed code-server, you can access it from an iPad.
- Getting self signed certificates certificates to work is involved, see below.
+## Using the code-server progressive web app (PWA)
 - Keyboard issues
  - May disappear sometimes [#1313](https://github.com/cdr/code-server/issues/1313), [#979](https://github.com/cdr/code-server/issues/979)
  - Some short cuts expectations may not be met
    - `command + n` opens new browser window instead of new file and difficult to even set to another quick key
    - In general it's just note worthy you most likely will need to edit keyboard shortcuts
  - No escape key by default on Magic Keyboard but everyone sets the globe key to be an escape key
    - Opinion: It's actually an awesome joy having the escape key at bottom of keyboard
 - Trackpad scrolling does not work [#1455](https://github.com/cdr/code-server/issues/1455)
  - [Bug tracking of a WebKit fix here](https://bugs.webkit.org/show_bug.cgi?id=210071#c13)
  - [tracking of WebKit patch](https://trac.webkit.org/changeset/270712/webkit)
  - Alternative: Install line-jump extension and use keyboard to nav by jumping large amount of lines
  - Alternative: Just use touch scrolling
 - See [issues tagged with the iPad label](https://github.com/cdr/code-server/issues?q=is%3Aopen+is%3Aissue+label%3AiPad) for more.
 - `ctrl+c` does not stop a long-running process in the browser
  - Tracking upstream issue here: [#114009](https://github.com/microsoft/vscode/issues/114009)
  - See [workaround](#ctrl-c-workaround)
-## How to install PWA
+To use code-server on an iPad, we recommend installing the code-server
 progressive web app (PWA):
-To install the code-server PWA, follow these steps:
+1. Open code-server in Safari.
 2. Click the **Share** icon.
 3. Click **Add to Home Screen**.
-1. Open code-server in Safari
+You can now open code-server from the Home screen, and when you do, you'll be
-2. Click the Share icon
+using the PWA. Running code-server as a PWA gets you more screen real estate and
-3. Click "Add to Home Screen"
+access to top-level keyboard shortcuts since its running like a native app.
-Now when you open code-server from the home screen, you will be using the PWA.
+For example, you can use `cmd+w` to close an active file in the workbench. You
-The advantages of this are more screen real estate and access to top-level keyboard shortcuts because it's running like an app.
+can add this to `keybindings.json`:
 An example shortcut is the `cmd+w` to close an active file in the workbench. You can add this to your `keybindings.json` by doing the following:
-1. Open up code-serer
+1. Open code-server
-2. `Command Palette > Open Keyboard Shortcuts (JSON)`
+2. Go to **Command Palette** > **Open Keyboard Shortcuts (JSON)**
-3. Add the following to your `keybindings.json`
+3. Add the following to `keybindings.json`
-```json
+   ```json
-{
+   {
     "key": "cmd+w",
     "command": "workbench.action.closeActiveEditor"
-}
+   }
-```
+   ```
-Test out command by hitting `cmd+w` to close an active file
+4. Test the command by using `cmd+w` to close an active file.
-## How to access code-server with a self signed certificate on iPad?
+## Access code-server with a self-signed certificate on an iPad
-Accessing a self signed certificate on iPad isn't as easy as accepting through all
+If you've installed code-server and are [running it with a self-signed
-the security warnings. Safari will prevent WebSocket connections unless the certificate
+certificate](./guide.md#using-a-self-signed-certificate), you may see multiple
-is installed as a profile on the device.
+security warnings from Safari. To fix this, you'll need to install the
 self-signed certificate generated by code-server as a profile on your device (you'll also need to do this to
 enable WebSocket connections).
-The below assumes you are using the self signed certificate that code-server
+### Certificate requirements
 generates for you. If not, that's fine but you'll have to make sure your certificate
 abides by the following guidelines from Apple: https://support.apple.com/en-us/HT210176
-**note**: Another undocumented requirement we noticed is that the certificate has to have `basicConstraints=CA:true`.
+- We're assuming that you're using the self-signed certificate code-server
  generates for you (if not, make sure that your certificate [abides by the
  guidelines issued by Apple](https://support.apple.com/en-us/HT210176)).
 - We've noticed that the certificate has to include `basicConstraints=CA:true`.
 - Your certificate must have a subject alt name that matches the hostname you'll
  use to access code-server from the iPad. You can pass this name to code-server
  so that it generates the certificate correctly using `--cert-host`.
-The following instructions assume you have code-server installed and running
+### Sharing a self-signed certificate with an iPad
-with a self signed certificate. If not, please first go through [./guide.md](./guide.md)!
+
 To share a self-signed certificate with an iPad:
 1. Get the location of the certificate code-server generated; code-server prints
   the certificate's location in its logs:
   ```console
   [2020-10-30T08:55:45.139Z] info - Using generated certificate and key for HTTPS: ~/.local/share/code-server/mymbp_local.crt
   ```
 2. Send the certificate to the iPad, either by emailing it to yourself or using
   Apple's Airdrop feature.
 3. Open the `*.crt` file so that you're prompted to go into Settings to install.
 4. Go to **Settings** > **General** > **Profile**, and select the profile. Tap **Install**.
 5. Go to **Settings** > **About** > **Certificate Trust Settings** and [enable
   full trust for your certificate](https://support.apple.com/en-us/HT204477).
 You should be able to access code-server without all of Safari's warnings now.
 **warning**: Your iPad must access code-server via a domain name. It could be local
-DNS like `mymacbookpro.local` but it must be a domain name. Otherwise Safari will
+DNS like `mymacbookpro.local`, but it must be a domain name. Otherwise, Safari will
-refuse to allow WebSockets to connect.
+not allow WebSockets connections.
-1. Your certificate **must** have a subject alt name that matches the hostname
+## Access code-server using Servediter
   at which you will access code-server from your iPad. You can pass this to code-server
   so that it generates the certificate correctly with `--cert-host`.
 2. Share your self signed certificate with the iPad.
   - code-server will print the location of the certificate it has generated in the logs.
-```
+If you are unable to get the self-signed certificate working, or you do not have a domain
-[2020-10-30T08:55:45.139Z] info    - Using generated certificate and key for HTTPS: ~/.local/share/code-server/mymbp_local.crt
+name to use, you can use [Servediter for code-server](https://apps.apple.com/us/app/servediter-for-code-server/id1504491325).
 ```
- You can mail it to yourself or if you have a Mac, it's easiest to just Airdrop to the iPad.
+> Servediter for code-server is **not** officially supported by the code-server team!
-3. When opening the `*.crt` file, you'll be prompted to go into settings to install.
+To use Servediter:
 4. Go to `Settings -> General -> Profile`, select the profile and then hit `Install`.
   - It should say the profile is verified.
 5. Go to `Settings -> About -> Certificate Trust Settings` and enable full trust for
   the certificate. [more apple support here](https://support.apple.com/en-us/HT204477)
 6. Now you can access code-server! 🍻
-### Servediter iPad App
+1. Download the app from the App Store.
 2. When prompted, provide your server information. If you are running a local
   server or a [Raspberry Pi connected via USB-C](#raspberry-pi-usb-c-network), you will input your settings
   into **Self Hosted Server**.
-If you are unable to get the self signed certificate working or you do not have a domain
+## Raspberry Pi USB-C network
 name to use, you can use the Servediter iPad App instead!
-**note**: This is not an officially supported app by the code-server team!
+We've heard of users having great success using code-server on an iPad connected
 to a Raspberry Pi via USB-C (the Raspberry Pi provides both power and direct
 network access). Setting this up requires you to turn on **Network over USB-C**
 on the Raspberry Pi, then continuing with code-server as usual on the iPad.
-Download [Serveediter](https://apps.apple.com/us/app/servediter-for-code-server/id1504491325) from the
+For more information, see:
 App Store and then input your server information. If you are running a local server or mabye a usb-c
 connected Raspberry Pi, you will input your settings into "Self Hosted Server".
-## Raspberry Pi USB-C Network
+- [General introduction to Pi as an iPad
-
+  accessory](https://www.youtube.com/watch?v=IR6sDcKo3V8)
 It is a bit out of scope for this project, however, great success is being reported using iPad on the go with just a single USB-C cable connected to a Raspberry Pi both powering and supplying direct network access. Many support articles already exist but the key steps boil down to turning on Network over USB-C on the Raspberry Pi itself and the rest of the steps are just like getting Code Server running any where else.
 Resources worthy of review:
 - [General intro to Pi as an iPad accessory](https://www.youtube.com/watch?v=IR6sDcKo3V8)
 - [iPad with Pi FAQ](https://www.youtube.com/watch?v=SPSlyqo5Q2Q)
- [Technical guide to perform the steps](https://www.geeky-gadgets.com/connect-a-raspberry-pi-4-to-an-ipad-pro-21-01-2020/)
+- [Technical guide to connecting a Raspberry Pi to an
  iPad](https://www.geeky-gadgets.com/connect-a-raspberry-pi-4-to-an-ipad-pro-21-01-2020/)
-> Here are my keys to success. I bought a 4" touch screen with fan included that attaches as a case to the Pi. I use the touch screen for anytime I have connection issues, otherwise I turn off the Pi screen. I gave my Pi a network name so I can easily connect at home on wifi or when on go with 1 usb-c cable that supplys both power and network connectivity. Lastly, not all usb-c cables are equal and not all will work so try different usb-c cables if you are going mad (confirm over wifi first then move to cable).
+You may also find the following tips from [Acker
->
+Apple](http://github.com/ackerapple/) helpful:
 > -- <cite>[Acker Apple](http://github.com/ackerapple/)</cite>
-## Ctrl C Workaround
+> Here are my keys to success. I bought a 4" touch screen with fan included that
 > attaches as a case to the Pi. I use the touch screen for anytime I have
 > connection issues, otherwise I turn off the Pi screen. I gave my Pi a network
 > name so I can easily connect at home on wifi or when on go with 1 usb-c cable
 > that supplys both power and network connectivity. Lastly, not all usb-c cables
 > are equal and not all will work so try different usb-c cables if you are going
 > mad (confirm over wifi first then move to cable).
-There is currently an issue with `ctrl+c` not stopping a running process in the integrated terminal. We have filed an issue upstream and are tracking [here](https://github.com/microsoft/vscode/issues/114009). As a temporary workaround, it works if you manually define the shortcut like so:
+## Recommendations
-1. Open Command Palette
+Once you can access code-server on your iPad, you may find the following tips
-2. Look for "Preferences: Open Keyboard Shortcuts (JSON)"
+and tricks helpful:
 3. Add this:
-```json
+- Use multi-task mode to make code changes and see the browser at the same time
-{
+  - This prevents the iOS background from dropping an app's state if you are
    switching between code-server and browser (with both in full-screen)
 - Be sure you are using the debug/terminal that is built into VS Code so that
  you don’t need another terminal app running
  - This also prevents switching between full screen apps and losing your view
    due to iOS' background app memory management
 ## Known issues
 - Getting self-signed certificates to work [is an involved
  process](#access-code-server-with-a-self-signed-certificate-on-an-ipad)
 - Keyboard issues:
  - The keyboard disappear sometimes
    [#1313](https://github.com/cdr/code-server/issues/1313),
    [#979](https://github.com/cdr/code-server/issues/979)
  - Some expectations regarding shortcuts may not be met:
    - `cmd + n` opens new browser window instead of new file, and it's difficult
      to set alternative as a workaround
    - In general, expect to edit your keyboard shortcuts
  - There's no escape key by default on the Magic Keyboard, so most users set
    the globe key to be an escape key
 - Trackpad scrolling does not work
  ([#1455](https://github.com/cdr/code-server/issues/1455))
  - Bug tracking of a WebKit fix
    [here](https://bugs.webkit.org/show_bug.cgi?id=210071#c13)
  - Tracking of [WebKit patch](https://trac.webkit.org/changeset/270712/webkit)
  - Alternatives:
    - Install line-jump extension and use keyboard to navigate by jumping large
      amount of lines
    - Use touch scrolling
 - `ctrl+c` does not stop a long-running process in the browser
  - Tracking upstream issue here:
    [#114009](https://github.com/microsoft/vscode/issues/114009)
  - See [workaround](#ctrl-c-workaround)
 Additionally, see [issues in the code-server repo that are tagged with the iPad
 label](https://github.com/cdr/code-server/issues?q=is%3Aopen+is%3Aissue+label%3AiPad)
 for more information.
 ### Workaround for issue with `ctrl+c` not stopping a running process in the terminal
 This's currently an issue with `ctrl+c` not stopping a running process in the
 integrated terminal. We have filed an issue upstream and are tracking
 [here](https://github.com/microsoft/vscode/issues/114009).
 In the meantime, you can manually define a shortcut as a workaround:
 1. Open the Command Palette
 2. Look for **Preferences: Open Keyboard Shortcuts (JSON)**
 3. Add the following snippet:
   ```json
   {
     "key": "ctrl+c",
     "command": "workbench.action.terminal.sendSequence",
     "args": {
       "text": "\u0003"
     },
     "when": "terminalFocus"
-}
+   }
-```
+   ```
-Source: [StackOverflow](https://stackoverflow.com/a/52735954/3015595)
+_Source: [StackOverflow](https://stackoverflow.com/a/52735954/3015595)_
 ## Recommendations
 Once you have code-server accessible to your iPad a few things could help save you time:
 - Use multi task mode to make code changes and see browser at the same time
  - Prevents iOs background dropping an App's state if you are full screen switching between code-server and browser
 - Be sure you are using the debug/terminal that is built into VS Code so that you don’t need another terminal app running
  - Again, prevents switching between full screen app and losing your view to iOs background app memory management
 - You should be of a mindset willing to deal and adapt with differences in having an imperfect experience, for the perceived joyful benefits of interacting with your computer in more intuitive ways
 ## By 2022 iPad coding more desirable on Arm Macs
 > This section is generalized opinions intended to inform fellow Apple product consumers of perceived over time changes coming down the line
 The general feeling from overall Apple movements recently, is that the Mac arm processors are in fact helping support the direction of having Macs with touch screens. Many great YouTube videos of interest call out highly suggestive evidence. In the past Apple has hard declared reasons of body fatigue and such as why not to encourage nor further developments on the iPad touch experience mixed with a keyboard/mouse/trackpad. Regardless, products and software have been released further supporting just that very experience.
 The iPad coding experience has been a joy for some of us that are willing to trade an imperfect experience for a uniquely effective focus driven experience. Note worthy, some of us think it's a trashy waste of time. This experience is undoubtably going to get better just by the work that can be seen by all parties, even in our own code-server attempt to make it better.
 Lastly, it is note worthy that if you have decided to incorporate a Raspberry Pi into you iPad coding experience, they are Arm processors. You are perfectly lined up with the future of Macs as well.
--- a/docs/npm.md
+++ b/docs/npm.md
@ -2,23 +2,28 @@
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 # npm Install Requirements
 - [Node.js version](#nodejs-version)
 - [Ubuntu, Debian](#ubuntu-debian)
 - [Fedora, CentOS, RHEL](#fedora-centos-rhel)
 - [Alpine](#alpine)
 - [macOS](#macos)
 - [FreeBSD](#freebsd)
 - [Issues with Node.js after version upgrades](#issues-with-nodejs-after-version-upgrades)
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
-If you're installing the npm module you'll need certain dependencies to build the native modules used by VS Code.
+If you're installing code-server via `npm`, you'll need to install additional
 dependencies required to build the native modules used by VS Code. This article
 includes installing instructions based on your operating system.
- Node.js: version `= 14`. Other versions may work, but your mileage may vary.
+## Node.js version
-_Note: We use the same major version of Node.js that is shipped in VSCode's Electron. VS Code also lists Node.js requirements. See [here](https://github.com/microsoft/vscode/wiki/How-to-Contribute#prerequisites)._
+We use the same major version of Node.js shipped with VSCode's Electron,
 which is currently `14.x`. VS Code also [lists Node.js
 requirements](https://github.com/microsoft/vscode/wiki/How-to-Contribute#prerequisites).
-Related:
+Using other versions of Node.js [may lead to unexpected
-
+behavior](https://github.com/cdr/code-server/issues/1633).
 - [#1633](https://github.com/cdr/code-server/issues/1633)
 ## Ubuntu, Debian
@ -58,3 +63,22 @@ xcode-select --install
 pkg install -y git python npm-node14 yarn-node14 pkgconf
 pkg install -y libinotify
 ```
 ## Issues with Node.js after version upgrades
 Occasionally, you may run into issues with Node.js.
 If you install code-server using `yarn` or `npm`, and you upgrade your Node.js
 version, you may need to reinstall code-server to recompile native modules.
 Sometimes, you can get around this by navigating into code-server's `lib/vscode`
 directory and running `npm rebuild` to recompile the modules.
 A step-by-step example of how you might do this is:
 1. Install code-server: `brew install code-server`
 2. Navigate into the directory: `cd /usr/local/Cellar/code-server/<version>/libexec/lib/vscode/`
 3. Recompile the native modules: `npm rebuild`
 4. Restart code-server
 If you need further assistance, post on our [GitHub Discussions
 page](https://github.com/cdr/code-server/discussions).
--- a/docs/requirements.md
+++ b/docs/requirements.md
@ -0,0 +1,55 @@
 # Requirements
 You'll need a machine on which you can run code-server. You can use a physical
 machine you have, or you can use a VM on GCP/AWS.
 At the minimum, we recommend:
 - 1 GB of RAM
 - 2 CPU cores
 You can use any Linux distribution, but [our
 docs](https://coder.com/docs/code-server/v3.10.2/guide) assume that you're using
 Debian hosted by Google Cloud (see the following section for instructions on
 setting this up).
 Your environment must have WebSockets enabled, since code-server uses WebSockets
 for communication between the browser and the server.
 ## Set up a VM on Google Cloud
 The following steps walk you through setting up a VM running Debian using Google
 Cloud (though you are welcome to use any machine or VM provider).
 If you're [signing up with Google](https://console.cloud.google.com/getting-started) for the first time, you should get a 12-month trial with
 $300 of credits.
 After you sign up and create a new Google Cloud Provider (GCP) project, create a
 new Compute Engine VM instance:
 1. Using the sidebar, navigate to **Compute Engine** > **VM Instances**.
 2. Click **Create Instance**.
 3. Provide a **name** for new instance.
 4. Choose the **region** that's closest to you based on [GCP
   ping](https://gcping.com/).
 5. Choose a **zone** (any option is fine).
 6. We recommend choose an **E2 series instance** from the [general-purpose
   family](https://cloud.google.com/compute/docs/machine-types#general_purpose).
 7. Change the instance type to **custom** and set at least **2 cores** and **2
   GB of RAM**. You can add more resources if desired, though you can also edit
   your instance at a later point.
 8. Though optional, we highly recommend switching the persistent disk to an SSD
   with at least 32 GB. To do so, click **change** under **Boot Disk**. Then,
   change the type to **SSD Persistent Disk**, and set the size to **32**. (You
   can also grow your disk at a later date).
 9. Go to **Networking** > **Networking Interfaces** and edit the existing
   interface to use a static internal IP. Click **Done** to save.
 10. If you don't have a [project-wide SSH
    key](https://cloud.google.com/compute/docs/instances/adding-removing-ssh-keys#project-wide),
    go to **Security** > **SSH Keys** to add your public key.
 11. Click **Create** to proceed.
 Notes:
 - To lower costs, you can shut down your server when you're not using it.
 - We recommend using the `gcloud cli` to avoid using the GCP Dashboard if possible.
--- a/docs/termux.md
+++ b/docs/termux.md
@ -2,69 +2,70 @@
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 # Termux
- [Termux](#termux)
+- [Install](#install)
-  - [Installation](#installation)
+- [Upgrade](#upgrade)
-  - [Upgrading](#upgrading)
+- [Known Issues](#known-issues)
-  - [Known Issues](#known-issues)
+  - [Search doesn't work](#search-doesnt-work)
-    - [Search issue](#search-issue)
+  - [Backspace doesn't work](#backspace-doesnt-work)
    - [Backspace not working](#backspace-not-working)
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
-# Termux
+Termux is a terminal application and Linux environment that you can also use to
 run code-server from your Android phone.
-Termux is an Android terminal application and Linux environment, which can also run code-server from your phone.
+## Install
-## Installation
+1. Install Termux from [F-Droid](https://f-droid.org/en/packages/com.termux/).
 1. Make sure it's up-to-date: `apt update && apt upgrade`
 1. Install required packages: `apt install build-essential python git nodejs yarn`
 1. Install code-server: `yarn global add code-server`
 1. Run code-server: `code-server` and navigate to localhost:8080 in your browser
-1. Install Termux from [F-Droid](https://f-droid.org/en/packages/com.termux/)
+## Upgrade
 2. Make sure it's up-to-date by running `apt update && apt upgrade`
 3. Install required packages: `apt install build-essential python git nodejs yarn`
 4. Install code-server: `yarn global add code-server`
 5. Run code-server: `code-server` and navigate to localhost:8080 in your browser
 ## Upgrading
 To upgrade run: `yarn global upgrade code-server --latest`
 ## Known Issues
-### Search issue
+The following details known issues and suggested workarounds for using
 code-server with Termux.
-There is a known issue with search not working on Android because it's missing `bin/rg`. To fix:
+### Search doesn't work
 There is a known issue with search not working on Android because it's missing
 `bin/rg` ([context](https://github.com/cdr/code-server/issues/1730#issuecomment-721515979)). To fix this:
 1. Install `ripgrep` with `pkg`
   ```sh
   pkg install ripgrep
   ```
 2. Make a soft link using `ln -s`
-```sh
+1. Make a soft link using `ln -s`
 # run this command inside the code-server directory
 ln -s $PREFIX/bin/rg ./lib/vscode/node_modules/vscode-ripgrep/bin/rg
 ```
-For more context, see [comment](https://github.com/cdr/code-server/issues/1730#issuecomment-721515979).
+   ```sh
   # run this command inside the code-server directory
   ln -s $PREFIX/bin/rg ./lib/vscode/node_modules/vscode-ripgrep/bin/rg
   ```
-### Backspace not working
+### Backspace doesn't work
-There is a known issue with the backspace key not working correctly when using the on-screen keyboard on Android. This is due to an upstream issue. Read more:
+When using Android's on-screen keyboard, the backspace key doesn't work
 properly. This is a known upstream issue:
- [Issues with Backspace in Codespaces on Android (Surface Duo)](https://github.com/microsoft/vscode/issues/107602)
+- [Issues with backspace in Codespaces on Android (Surface Duo)](https://github.com/microsoft/vscode/issues/107602)
 - [Support mobile platforms](https://github.com/xtermjs/xterm.js/issues/1101)
-Workaround #1: Modify Keyboard Dispatch Settings
+There are two workarounds.
 **Option 1:** Modify keyboard dispatch settings
 1. Open the Command Palette
-2. Search for "Preferences: Open Settings (JSON)"
+2. Search for **Preferences: Open Settings (JSON)**
 3. Add `"keyboard.dispatch": "keyCode"`
-The backspace button should work now.
+The backspace button should work at this point.
 (Thanks to @Nefomemes for the suggestion! See [comment](https://github.com/cdr/code-server/issues/1141#issuecomment-789463707))
-Workaround #2: use a Bluetooth keyboard.
+_Thanks to @Nefomemes for the [suggestion](https://github.com/cdr/code-server/issues/1141#issuecomment-789463707)!_
-For more context, see issues:
+**Option 2:** Use a Bluetooth keyboard.
 - [500 error: 3.9.2 not working on Android + Termux](https://github.com/cdr/code-server/issues/3036)
 - [Issue #3079](https://github.com/cdr/code-server/issues/3079)
--- a/docs/triage.md
+++ b/docs/triage.md
@ -1,37 +1,35 @@
 # Triage
 ## Filter
 Triaging code-server issues is done with the following issue filter:
-```
+```text
 is:issue is:open no:project sort:created-asc -label:blocked -label:upstream -label:waiting-for-info -label:extension-request
 ```
 This will show issues that:
 1. Are open.
-2. Have no assigned project.
+1. Have no assigned project.
-3. Are not `blocked` or tagged for work by `upstream` (VS Code core team)
+1. Are not `blocked` or tagged for work by `upstream` (the VS Code core team).
-   - If an upstream issue is detrimental to the code-server experience we may fix it in
+   If an upstream issue is detrimental to the code-server experience we may fix
-     our patch instead of waiting for the VS Code team to fix it.
+   it in our patch instead of waiting for the VS Code team to fix it. Someone
-   - Someone should periodically go through these issues to see if they can be unblocked
+   should periodically go through these issues to see if they can be unblocked!
-     though!
+1. Are not labeled `waiting-for-info`.
-4. Are not in `waiting-for-info`.
+1. Are not extension requests.
 5. Are not extension requests.
-## Process
+## Triage process
-1. If an issue is a question/discussion it should be converted into a GitHub discussion.
+1. If an issue is a question/discussion, it should be converted into a GitHub
-2. Next, give the issue the appropriate labels and feel free to create new ones if
+   discussion.
-   necessary.
+1. Otherwise, give the issue the appropriate labels (feel free to create new
-   - There are no hard and set rules for labels. We don't have many so look through and
+   ones if necessary). There are no hard and set rules for labels. We don't have
-     see how they've been used throughout the repository. They all also have descriptions.
+   many so look through and see how they've been used throughout the repository.
-3. If more information is required, please ask the submitter and tag as
+   They all also have descriptions.
 1. If more information is required, please ask the submitter and tag as
   `waiting-for-info` and wait.
-4. Finally, the issue should be moved into the
+1. Finally, the issue should be moved into the
-   [code-server](https://github.com/cdr/code-server/projects/1) project where we pick
+   [code-server](https://github.com/cdr/code-server/projects/1) project where we
-   out issues to fix and track their progress.
+   pick out issues to fix and track their progress.
-We also use [milestones](https://github.com/cdr/code-server/milestones) to track what
+We also use [milestones](https://github.com/cdr/code-server/milestones) to track
-issues are planned/or were closed for what release.
+what issues are planned/or were closed for what release.
--- a/docs/upgrade.md
+++ b/docs/upgrade.md
@ -0,0 +1,5 @@
 # Upgrade
 To upgrade code-server, install the new version over the old version. All user
 data is in `~/.local/share/code-server`, so they are preserved between
 installations.