From ef0ee441848c8bcc7204cc333340baf8b026d4b6 Mon Sep 17 00:00:00 2001 From: Francis Date: Wed, 18 Sep 2024 07:55:43 +0100 Subject: [PATCH] First draft for PR - Still to be "ported" over and cleaned up from the PoC is the section on installing Java. - The FAQ also has some of the older content commented out with a planned return when brain starts working again properly. - Not all feedback has been acted on yet and one change in particular (on finding a terminal emulator-like app) could already benefit from being moved/refactored. --- docusaurus.config.js | 23 ++++++++++++ sidebarsUserGuide.js | 33 +++++++++++++++++ src/pages/index.mdx | 8 +++++ userguide/docs/faq.md.orig | 12 +++++++ userguide/docs/faq.mdx | 70 ++++++++++++++++++++++++++++++++++++ userguide/docs/index.mdx | 27 ++++++++++++++ userguide/docs/installer.mdx | 16 +++++++++ userguide/docs/java.mdx | 49 +++++++++++++++++++++++++ 8 files changed, 238 insertions(+) create mode 100644 sidebarsUserGuide.js create mode 100644 userguide/docs/faq.md.orig create mode 100644 userguide/docs/faq.mdx create mode 100644 userguide/docs/index.mdx create mode 100644 userguide/docs/installer.mdx create mode 100644 userguide/docs/java.mdx diff --git a/docusaurus.config.js b/docusaurus.config.js index 071dd3c6..7cd9ccee 100644 --- a/docusaurus.config.js +++ b/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", diff --git a/sidebarsUserGuide.js b/sidebarsUserGuide.js new file mode 100644 index 00000000..22a483bf --- /dev/null +++ b/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; diff --git a/src/pages/index.mdx b/src/pages/index.mdx index e6987201..f9259e5b 100644 --- a/src/pages/index.mdx +++ b/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" /> +
+ +
diff --git a/userguide/docs/faq.md.orig b/userguide/docs/faq.md.orig new file mode 100644 index 00000000..1747ccb8 --- /dev/null +++ b/userguide/docs/faq.md.orig @@ -0,0 +1,12 @@ +--- +sidebar_position: 4 +--- + +# Common Pitfalls + +This section aims to provide answers to frequently asked questions as well as solutions to common pitfalls when running modded Minecraft. + + + +[NeoForge Discord]: https://discord.neoforged.net/ +[JarFix]: https://johann.loefflmann.net/downloads/jarfix.exe \ No newline at end of file diff --git a/userguide/docs/faq.mdx b/userguide/docs/faq.mdx new file mode 100644 index 00000000..824e496b --- /dev/null +++ b/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]. + + + +[JarFix]: https://johann.loefflmann.net/downloads/jarfix.exe +[Locating Terminal Application]: ./java.mdx#locating-terminal-application \ No newline at end of file diff --git a/userguide/docs/index.mdx b/userguide/docs/index.mdx new file mode 100644 index 00000000..f3932ed1 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/userguide/docs/installer.mdx b/userguide/docs/installer.mdx new file mode 100644 index 00000000..23e3adb4 --- /dev/null +++ b/userguide/docs/installer.mdx @@ -0,0 +1,16 @@ +--- +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]. + +[Troubleshooting the NeoForge Installer]: ./faq.x#troubleshooting-the-installer +[FAQ]: ./faq.mdx \ No newline at end of file diff --git a/userguide/docs/java.mdx b/userguide/docs/java.mdx new file mode 100644 index 00000000..15c558fc --- /dev/null +++ b/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 whether you already have Java installed and how where to obtain a copy when it is not already installed. + +If you are sure that you do not already have Java installed, proceed the final section entitled [Installing Java] 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 applications to use differs based on the OS that is running: + + + + On Windows, one of the following should be available: + - Windows Terminal + - PowerShell + - Command Prompt (aka `cmd`) + + + On macOS there is the `Terminal.app` often found on the Finder dock. + + + 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. + + + +### 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 \ No newline at end of file