Split install instructions into separate pages

docs/index.md

@@ -3,7 +3,8 @@
 
 ## What is `master`? {#master}
 
-`master` is the name of RGBDS' main development branch. It's usually employed as a version name to refer to the state of in-development RGBDS: it contains the latest changes as they are pushed, but for this reason it's very unstable.
+`master` is the name of RGBDS' main development branch.
+It's used to refer to "bleeding-edge" RGBDS, containing the latest changes as they are pushed.
 
 ### Pros and cons of `master` over releases
 
@@ -15,7 +16,7 @@ Pros:
 
 Cons:
 
-- Tested, but unstable, so expect things to break often
+- Tested, but less stable, so expect things to break occasionally
 - Must be compiled manually, unless you [use our CI](/install/master#using-our-ci)
 - Updated often
 

docusaurus.config.js

@@ -33,31 +33,9 @@ const config = {
   organizationName: "gbdev",
   projectName: "rgbds-www",
 
-  plugins: [
-    [
-      "@docusaurus/plugin-client-redirects",
-      {
-        redirects: [
-          "gbz80.7",
-          "rgbasm.1",
-          "rgbasm.5",
-          "rgbds.5",
-          "rgbds.7",
-          "rgbfix.1",
-          "rgbgfx.1",
-          "rgblink.1",
-          "rgblink.5",
-        ].map((page) => {
-          return { from: `/docs/${page}`, to: `/docs/${latestStable}/${page}` };
-        }),
-      },
-    ],
-    "docusaurus-plugin-matomo",
-  ],
-
   presets: [
     [
-      "classic",
+      "@docusaurus/preset-classic",
       /** @type {import('@docusaurus/preset-classic').Options} */
       {
         docs: {
@@ -81,6 +59,37 @@ const config = {
     ],
   ],
 
+  plugins: [
+    [
+      "@docusaurus/plugin-content-docs",
+      {
+        id: "install",
+        path: "install",
+        routeBasePath: "install",
+        sidebarPath: "./installSidebars.js",
+      }
+    ],
+    [
+      "@docusaurus/plugin-client-redirects",
+      {
+        redirects: [
+          "gbz80.7",
+          "rgbasm.1",
+          "rgbasm.5",
+          "rgbds.5",
+          "rgbds.7",
+          "rgbfix.1",
+          "rgbgfx.1",
+          "rgblink.1",
+          "rgblink.5",
+        ].map((page) => {
+          return { from: `/docs/${page}`, to: `/docs/${latestStable}/${page}` };
+        }),
+      },
+    ],
+    "docusaurus-plugin-matomo",
+  ],
+
   themeConfig:
     /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
     ({

install/index.md

@@ -0,0 +1,31 @@
+---
+sidebar_label: Available install methods
+---
+
+# Installing RGBDS
+
+Most people will want to use a stable release (the more recent the better).
+
+These are the operating systems for which pre-built executables of recent releases of RGBDS are available:
+- [Linux](linux.md)
+- [macOS](macos.md)
+- [Windows](windows.md)
+
+If none of these options fit your needs, you can [build from source](source.md).
+
+### Docker
+
+We distribute an [official container image for RGBDS](https://github.com/gbdev/rgbds/pkgs/container/rgbds).
+It contains the built executables *and* the build dependencies, in case you want to compile from source.
+
+```bash
+docker pull ghcr.io/gbdev/rgbds:latest
+```
+
+### Installing a development version
+
+If you are willing to help us test new features, consider [using a development version](master.md).
+
+### Managing multiple versions
+
+If you need to frequently switch between different versions of RGBDS, consider using [rgbenv](https://github.com/gbdev/rgbenv), the RGBDS version manager.

install/linux.md

@@ -0,0 +1,28 @@
+---
+sidebar_label: Linux
+---
+
+# Installing RGBDS on Linux
+
+## Using your package manager
+
+Check if RGBDS is available in your distribution's software center or package manager repositories.
+If a satisfactory version is available, it is a good idea to install from there.
+
+## Using our pre-built binaries
+
+1. Go the [latest release](https://github.com/gbdev/rgbds/releases/latest) (or pick [a specific version](https://github.com/gbdev/rgbds/releases))
+2. Under "Assets" at the bottom, download <code>rgbds-<var>&lt;version&gt;</var>-linux-x86_64.tar.xz</code> (for example, version 0.7.0 would have `rgbds-0.7.0-linux-x86_64.tar.xz`)
+3. Extract the .tar.xz file into a new directory, and run `install.sh` as root in that directory. E.g.:
+   ```console
+   % mkdir rgbds
+   % tar xf rgbds-0.7.0-linux-x86_64.tar.xz -C rgbds
+   % cd rgbds
+   % sudo ./install.sh
+   ```
+4. Check that RGBDS was correctly installed by running `rgbasm -V`.
+   It should print out the version number you installed!
+
+---
+
+If none of these options are suitable to you, [build RGBDS from source](source.md).

install/macos.md

@@ -0,0 +1,40 @@
+---
+sidebar_label: macOS
+---
+
+# Installing RGBDS on macOS
+
+## Using the Homebrew package manager
+
+On recent macOS major releases[^1], RGBDS is available on [Homebrew](https://brew.sh) as the [`rgbds` package](https://formulae.brew.sh/formula/rgbds).
+
+```bash
+brew install rgbds
+```
+
+Then you will be able to update RGBDS at any time by simply running `brew update` then `brew upgrade`!
+
+You can also install the [`master` branch](/docs/master) by passing the `--HEAD` flag:
+```bash
+brew install rgbds --HEAD
+```
+
+## Using our pre-built binaries
+
+1. Go the [latest release](https://github.com/gbdev/rgbds/releases/latest) (or pick [a specific version](https://github.com/gbdev/rgbds/releases))
+2. Under "Assets" at the bottom, download <code>rgbds-<var>&lt;version&gt;</var>-macos-x86-64.zip</code> (for example, version 0.7.0 would have `rgbds-0.7.0-macos-x86-64.zip`).
+3. Extract the .zip file into a new directory, and run `install.sh` as root inside that directory.
+   For example, you can do that with these Console commands:
+   ```console
+   % unzip -d rgbds rgbds-0.7.0-macos-x86-64.zip
+   % cd rgbds
+   % sudo ./install.sh
+   ```
+4. Check that RGBDS was correctly installed by running `rgbasm -V`.
+   It should print out the version number you installed!
+
+---
+
+If none of these options are suitable to you, [build RGBDS from source](source.md).
+
+[^1]: Older macOS systems have been reported to compile for several days with Homebrew.

src/pages/install/master.md → install/master.md

@@ -1,30 +1,22 @@
+---
+sidebar_label: Using a development version
+---
 
 # Using RGBDS `master`
 
 `master` is the name of RGBDS' main development branch.
 Using a "master" version of RGBDS means using an in-development version: this means you get access to the newest features faster (and you help test them!), but it also means that they have undergone a little less testing.
 
 We are very grateful to all who takes the time to use `master` versions; all of you help make the releases better for everyone.
-But, if you don't want to, you can [go back to the install page](/install).
 
 ## Using a package manager
 
-Your package manager *may* have a `master` version of RGBDS available, such as Arch's [`rgbds-git` AUR package](https://aur.archlinux.org/packages/rgbds-git).
+Your package manager *may* have a `master` version of RGBDS available, such as Arch Linux [`rgbds-git` AUR package](https://aur.archlinux.org/packages/rgbds-git).
 If that is the case, it is recommended to use that, as it should be simpler and integrate better with the rest of your system.
 
-As this is highly OS-specific, we cannot provide any generic instructions.
-Sorry!
-
 ## Building it yourself
 
-:::tip
-
-If your package manager is not an option, this is the preferred way.
-Unless you are on Windows, in which case consider [using our CI](#using-our-ci) instead.
-
-:::
-
-[Build the source](/install/source) as usual, but replace step 1 (getting the sources) with getting the `master` repo instead.
+[Build the source](source.md) as usual, but replace step 1 (getting the sources) with getting the `master` repo instead.
 The recommended way is to clone the repo (see [GitHub's help on it](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository) if you have trouble), but you can also download the repo as ZIP.
 
 Then, follow the rest of the instructions to build from source.

src/pages/install/source.md → install/source.md

@@ -1,3 +1,6 @@
+---
+sidebar_label: Building RGBDS yourself
+---
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
@@ -24,11 +27,9 @@ You first need to get the source files to be compiled, using one of the methods
 <Tabs>
 <TabItem value="snapshot" label="Downloading source snapshots">
 
-1. [Pick a release](/docs).
-2. Under the "GitHub links" heading, follow the `release page` link.
-3. Go to "**Assets**" at the bottom of that page.
-4. Download any of the last three listed files (`rgbds-<version>.tar.gz`, "Source code (`zip`)", or "Source code (`tar.gz`)").
-5. Extract ("unzip") the file.
+1. Go the [latest release](https://github.com/gbdev/rgbds/releases/latest) (or pick [a specific version](https://github.com/gbdev/rgbds/releases))
+2. Under "Assets" at the bottom, download any of the last three listed files (<code>rgbds-<var>&lt;version&gt;</var>.tar.gz</code>, "Source code (`zip`)", or "Source code (`tar.gz`)").
+3. Extract ("unzip") the file.
 
 </TabItem>
 <TabItem value="git" label="Using Git">

install/windows.md

@@ -0,0 +1,101 @@
+---
+sidebar_label: Windows
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Installing RGBDS on Windows
+
+The install instructions are a bit different depending on the environment in which you wish to use RGBDS.
+
+<Tabs>
+<TabItem value="wsl" label="WSL">
+
+Using WSL is recommended if your version of Windows supports it (which Windows 10 and 11 do).
+
+Please refer to [the install instructions](linux.md) for your WSL's running Linux distribution.
+You can check what your WSL distribution is by running `wsl -l -v` in the Command Prompt.
+(The default Linux distribution on WSL is Ubuntu, whose package manager is `apt`.)
+
+</TabItem>
+<TabItem value="cygwin" label="Cygwin / MSYS2">
+
+1. Go the [latest release](https://github.com/gbdev/rgbds/releases/latest) (or pick a specific version from [the list](https://github.com/gbdev/rgbds/releases)).
+2. Under "Assets" at the bottom, download either <code>rgbds-<var>&lt;version&gt;</var>-win32.zip</code> (for 32-bit Windows) or <code>rgbds-<var>&lt;version&gt;</var>-win64.zip</code> (for 64-bit Windows).
+   (For example, version 0.7.0 for 64-bit Windows would have `rgbds-0.7.0-win64.zip`).
+3. Unzip the .zip file.
+   It should give you the RGBDS `.exe` files and a couple of `.dll` files.
+4. Copy all of those `.exe` and `.dll` files to the `/usr/local/bin` directory of your Cygwin/MSYS2 installation.
+   (You can learn its equivalent Windows path by running `cygpath -w /usr/local/bin` in the Cygwin terminal.)
+
+   :::caution
+
+   Do not put them in a subdirectory (e.g. `/usr/local/bin/rgbds/`)!
+   This would not work.
+
+   :::
+
+After that, you should be able to use RGBDS from within the Cygwin/MSYS2 terminal, which you can confirm by running `rgbasm -V`.
+
+If `rgbasm -V` doesn't work, check that `/usr/local/bin` is listed in your Cygwin/MSYS2 `PATH` (run `echo $PATH` to check).
+If it isn't listed, you must add it (e.g. run `echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc`, then close your Cygwin terminal and open a new one).
+
+:::tip
+
+If you can choose between using Cygwin or MSYS2, be advised that Cygwin is slower and has been reported to cause a bit of trouble to some.
+
+:::
+
+</TabItem>
+<TabItem value="win32" label="None of those">
+
+1. Go the [latest release](https://github.com/gbdev/rgbds/releases/latest) (or pick a specific version from [the list](https://github.com/gbdev/rgbds/releases))
+2. Under "Assets" at the bottom, download either <code>rgbds-<var>&lt;version&gt;</var>-win32.zip</code> (for 32-bit Windows) or <code>rgbds-<var>&lt;version&gt;</var>-win64.zip</code> (for 64-bit Windows).
+   (For example, version 0.7.0 for 64-bit Windows would have `rgbds-0.7.0-win64.zip`).
+3. Unzip the .zip file.
+   It should give you the RGBDS `.exe` files and a couple of `.dll` files.
+4. Either:
+   - ...put all of the files in a directory, then add that directory to Windows' `PATH`.
+     This will *permanently* allow you to use RGBDS *from any directory*.
+
+     <Tabs>
+     <TabItem value="gui" label="Graphically">
+
+       1. Open the Environment Variables dialog for your account.
+          You can do this by either:
+          - ...typing "edit environment variables for your account" in the Start menu's Search box and clicking the Control Panel item that's found.
+          - ...opening the Control Panel, clicking its "User Accounts" item, clicking the "User Accounts" heading in that item, and clicking "Change my environment variables" in the sidebar.
+       2. Click the "Path" line in the **top** panel to highlight it.
+       6. Click "Edit..." to open the "Edit environment variable" dialog for "Path".
+       7. Click "Browse...", select the folder that the RGBDS files are in, and click OK.
+       8. The folder should be added to the bottom of the "Path" list.
+          Make sure that the new entry (which should be highlighted) is at the bottom of the list; if not, click on "Move Down" until it is.
+       9. Click "OK" to finish the "Edit environment variable" dialog, and again for the "Environment Variables" dialog.
+
+     </TabItem>
+     <TabItem value="cmd" label="Command Prompt">
+
+       Run the command <code>setx PATH "%PATH%<var>&lt;rgbds_path&gt;</var>;"</code>, replacing <code><var>&lt;rgbds_path&gt;</var></code> with the path to the directory that contains `rgbasm.exe`, `rgblink.exe`, etc.
+       Then close the Command Prompt and open a new one for the changes to take effect.
+
+       If you only want to modify the `PATH` temporarily, instead of the permanent [`setx`](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/setx) command, you can use the **temporary** [`set`](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1).
+
+     </TabItem>
+     <TabItem value="pwsh" label="PowerShell">
+
+       Run the command <code>setx PATH \$\{Env:PATH\}<var>&lt;rgbds_path&gt;</var>;</code>, replacing <code><var>&lt;rgbds_path&gt;</var></code> with the path to the directory that contains `rgbasm.exe`, `rgblink.exe`, etc.
+       Then close the PowerShell window and open a new one for the changes to take effect.
+
+       If you only want to modify the `PATH` temporarily, instead of the permanent [`setx`](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/setx) command, you can use the **temporary** [`set`](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1).
+
+     </TabItem>
+     </Tabs>
+
+   - ...or put all of the files in your project's directory.
+   - ...or put all of the files in a directory already in the `PATH`.
+5. RGBDS can now be used from your favorite command line (most likely the Command prompt or PowerShell).
+   You can test it by running `rgbasm -V`, which should print the version you installed!
+
+</TabItem>
+</Tabs>

installSidebars.js

@@ -0,0 +1,22 @@
+// @ts-check
+
+/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
+const sidebars = {
+  nav: [
+    "index",
+    {
+      type: "category",
+      label: "Supported OSes",
+      collapsible: false,
+      items: [
+        "linux",
+        "macos",
+        "windows",
+      ],
+    },
+    "source",
+    "master",
+  ],
+};
+
+module.exports = sidebars;