First draft for user guide PR

docusaurus.config.js

@@ -83,6 +83,22 @@ const config = {
         },
       },
     ],
+    [
+      "@docusaurus/plugin-content-docs",
+      {
+        id: "userguide",
+        path: "userguide",
+        routeBasePath: "userguide",
+        sidebarPath: require.resolve("./sidebarsUserGuide.js"),
+        lastVersion: "current",
+        includeCurrentVersion: true,
+        versions: {
+          current: {
+            label: "0.1",
+          },
+        },
+      },
+    ],
   ],
 
   themeConfig:
@@ -114,6 +130,13 @@ const config = {
             docsPluginId: "neogradle",
             label: "NeoGradle Documentation",
           },
+          {
+            type: "docSidebar",
+            sidebarId: "ugSidebar",
+            position: "left",
+            docsPluginId: "userguide",
+            label: "NeoForge User Guide",
+          },
           {
             type: "docsVersionDropdown",
             position: "right",

sidebarsUserGuide.js

@@ -0,0 +1,33 @@
+/**
+ * Creating a sidebar enables you to:
+ - create an ordered group of docs
+ - render a sidebar for each doc of that group
+ - provide next/previous navigation
+
+ The sidebars can be generated from the filesystem, or explicitly defined here.
+
+ Create as many sidebars as you want.
+ */
+
+// @ts-check
+
+/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
+const sidebars = {
+  // By default, Docusaurus generates a sidebar from the docs folder structure
+  ugSidebar: [{ type: "autogenerated", dirName: "docs" }],
+
+  // But you can create a sidebar manually
+  /*
+  tutorialSidebar: [
+    'intro',
+    'hello',
+    {
+      type: 'category',
+      label: 'Tutorial',
+      items: ['tutorial-basics/create-a-document'],
+    },
+  ],
+   */
+};
+
+module.exports = sidebars;

src/pages/index.mdx

@@ -26,6 +26,14 @@ If you would like to contribute to the docs, read [Contributing to the Docs][con
         linkTitle="Read More"
       />
     </div>
+    <div class="col col--6" style={{padding: '10px'}}>
+      <Card
+        title="NeoForge User Guide"
+        body="Learn how to install NeoForge for both client and server, we well as some of the pitfalls you might experience along the way."
+        link="/userguide/docs/"
+        linkTitle="Read More"
+      />
+    </div>
   </div>
 </div>
 

userguide/docs/faq.mdx

@@ -0,0 +1,70 @@
+---
+sidebar_position: 3
+---
+
+# Frequently Asked Questions
+
+This section aims to answer some common questions as well as covering some pitfals you might experience when using the NeoForge installer.
+
+## Troubleshooting the NeoForge Installer
+
+### Troubleshooting the NeoForge Installer on Windows
+
+File associations for executing Java applications are sometimes missing or otherwise misconfigured.
+
+For example, running the installer may momentarily flash up a black window, present the `Open with ...` dialog box, or it might open in a file archiving program such as WinRAR or 7-Zip.
+
+To fix this, download and run (double-click) [JarFix], a program designed to fix broken or missing file associations.
+
+Once complete, restart your computer and try running the installer again.
+
+### Troubleshooting the NeoForge Installer on Linux
+
+File associations for executing Java applications are often missing completely on Linux distributions.
+
+In order to run the installer you may need to execute it manually in a terminal.
+
+For instance, with an installer for NeoForge version `21.1.54`, running the following in a terminal should bring up its GUI:
+
+```
+$ java -jar neoforge-21.1.54-installer.jar
+```
+
+For pointers on how to find a terminal application on Linux, see [Locating Terminal Application].
+
+<!--
+
+## Troubleshooting NeoForge
+
+## The installer crashed and I don't know why!
+
+Most users won't experience any issues when running the installer, but sometimes things do go wrong.  The installer should create a log file, with the same name as the installer, only with a `.log` file extension instead of `.jar`.  The installer log file can be used to find out what went wrong.
+
+Let's say that you downloaded the installer for NeoForge version `21.1.42` and saved the file to your desktop.  The log file from the installer should be on your desktop with a filename of `neoforge-21.1.42-installer.log`.
+
+You might be able to figure out why the installer failed by reading the log file but, if you're unsure of how to interpret its contents, join the [NeoForge Discord] and ask in the `#user-support` channel.
+
+:::note
+If you have an outdated version of Java 8 installed on your computer, the installer may fail due to outdated SSL certificates that are bundled with it.  Upgrading to a newer version of Java should fix this.
+:::
+
+## My game crashed and it said something about drivers?
+
+Due to an interaction between NeoForge's early-loading screen and outdated/buggy graphics card (GPU) drivers, the game may crash shortly after loading.  This can sometimes be fixed by upgrading the drivers for your GPU.
+
+:::note
+It's possible that your computer may have multiple GPUs, including one which is integrated into the CPU itself as well as a dedicated (also known as discrete) GPU.  If you don't know how many GPUs you have or which drivers to update, you can ask for help in the `#user-support` channel on the [NeoForge Discord] server.
+:::
+
+It might be possible to fix by updating your drivers.  To update your drivers, use one of the following tools provided by the three most common brands:
+
+- **Intel**: https://www.intel.com/content/www/us/en/support/detect.html
+
+- **AMD**: https://www.amd.com/en/support
+
+- **NVIDIA**: https://www.nvidia.com/download/index.aspx
+
+-->
+
+[JarFix]: https://johann.loefflmann.net/downloads/jarfix.exe
+[Locating Terminal Application]: ./java.mdx#locating-terminal-application

userguide/docs/index.mdx

@@ -0,0 +1,27 @@
+---
+sidebar_position: 0
+---
+
+# NeoForge User Guide
+
+## Introduction
+
+Whether you are a regular player, pack developer or server administrator, this guide is intended to help you through the process of preparing your computer to run NeoForge, as well as answer some frequently asked questions.
+
+## Prerequisites
+
+In order to install Neoforge, you will first need to have Java installed on your computer.
+
+If you are unsure whether you already have Java installed, proceed to the [Checking for and Installing Java] section.
+
+Otherwise, continue on to the [Installing NeoForge] section.
+
+## Further Help
+
+This document covers some of the issues you may face as a user of NeoForge, however it is not intended to be exhaustive, and you may run into a problem which is not covered here.
+
+The NeoForged project has a [Discord] server, including a `#user-support` channel, where you can ask questions and seek further support.
+
+[Discord]: https://discord.neoforged.net/
+[Checking for and Installing Java]: ./java.mdx
+[Installing NeoForge]: ./installer.mdx

userguide/docs/installer.mdx

@@ -0,0 +1,35 @@
+---
+sidebar_position: 2
+---
+
+# Installing NeoForge
+
+## Running The Installer
+
+The NeoForge installer is OS-agnostic and is universal in that it can be used to install on both the client and server.
+
+With Java installed, you should be able to just double-click the installer's `.jar` file and proceed from there.
+
+If double-clicking does not work, or your OS presents you with an error when doing so, see the section [Troubleshooting the NeoForge Installer] of the [FAQ].
+
+## Installing NeoForge on a Server
+
+You might want to install NeoForge on a "headless" server which does not have a GUI and therefore no means of double-clicking to run the installer.
+
+Usually this will mean that you need to use remote-access software such as [OpenSSH] to open a terminal and install NeoForge via the command line.
+
+Once you have opened a connection to the server you want to install on, the process is similar to that in the [] section of the [FAQ] with one extra `--installServer`.
+
+For example, to install a NeoForge server, version `21.1.51`, run the following command:
+
+```
+java -jar neoforge-21.1.51-installer.jar --installServer
+```
+
+This command will install the NeoForge server to the current working directory by default.
+
+If this is not what you want, specify the path you want to install to after the `--installServer`, e.g. by replacing the last `--installServer` with `--installServer /path/to/install/to`.
+
+[Troubleshooting the NeoForge Installer]: ./faq.mdx#troubleshooting-the-installer
+[FAQ]: ./faq.mdx
+[OpenSSH]: https://www.openssh.com/

userguide/docs/java.mdx

@@ -0,0 +1,49 @@
+---
+sidebar_position: 1
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Checking for and Installing Java
+
+This section provides instructions on how to check your computer for an existing Java installation.
+
+If you are sure that you do not already have Java installed, you can skip to the [Installing Java] section of this article below.
+
+## Checking for Existing Java Installation
+
+To find out if you already have Java, you will need to locate and run the terminal application that is provided by your OS.
+
+### Location Terminal Application
+
+The name of the application to use differs based on the OS that is running:
+
+<Tabs defaultValue="windows">
+  <TabItem value="windows" label="Windows">
+    On Windows, one of the following should be available:
+    - Windows Terminal
+    - PowerShell
+    - Command Prompt (aka `cmd`)
+  </TabItem>
+  <TabItem value="macos" label="macOS">
+    On macOS there is the `Terminal.app` often found on the Finder dock.
+  </TabItem>
+  <TabItem value="linux" label="Linux">
+    On Linux, using your window manager's main menu, you should have at least one such application, usually named just `Terminal` though could have other names such as `Console, `Konsole` or similar.
+  </TabItem>
+</Tabs>
+
+### Testing for Installed Java Version
+
+Once you have located your OS's terminal application, run the command `java -version` which should present you with information similar to the following:
+
+```
+openjdk version "21.0.4" 2024-07-16 LTS
+OpenJDK Runtime Environment Temurin-21.0.4+7 (build 21.0.4+7-LTS)
+OpenJDK 64-Bit Server VM Temurin-21.0.4+7 (build 21.0.4+7-LTS, mixed mode, sharing)
+```
+
+## Installing Java
+
+[Installing Java]: ./java.mdx#installing-java