From 3d458126778f15395a3e66e401a836ddee5afec7 Mon Sep 17 00:00:00 2001 From: Joshua Castle <26531652+Kas-tle@users.noreply.github.com> Date: Sun, 14 Jul 2024 18:49:12 -0700 Subject: [PATCH] Add contribution instructions Signed-off-by: Joshua Castle <26531652+Kas-tle@users.noreply.github.com> --- CONTRIBUTING.md | 137 +++++++++++++++++++++------ README.md | 67 ++++++------- docs/geyser/custom-blocks.md | 4 +- docs/geyser/custom-items.md | 4 +- docs/geyser/custom-resource-packs.md | 9 ++ docs/geyser/custom-skulls.md | 4 +- sidebars.ts | 16 +++- 7 files changed, 168 insertions(+), 73 deletions(-) create mode 100644 docs/geyser/custom-resource-packs.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 13f7a49..fdc4b05 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,50 +1,131 @@ -# Contributing +If you would like to contribute to the wiki, please [open a pull request](https://github.com/GeyserMC/GeyserWebsite/pulls). -If you would like to contribute to the wiki, please [open a pull request](https://github.com/GeyserMC/GeyserWiki/pulls). +Small changes can be made directly in the GitHub interface, but larger changes should be made by cloning the repository and running the website locally, ideally using an IDE with TypeScript support (e.g. [Visual Studio Code](https://code.visualstudio.com/)). -### Creating a new page +## Adding a Supported Hosting Provider -Most documentation is in the `docs` folder, where you can add new pages or edit the current ones. -If a new page is being added make sure you add its page properties at the beginning of the file. -Make sure that the file extension is .md - in this case `pagetitle.md`. +Supported hosting providers are listed in `src/data/providers.ts`. Hosting providers are grouped into three subcategories: -### Example page layout +- `built_in`: Providers that have fully automatic Geyser installation. +- `supported`: Providers that work with Geyser but require manual installation. +- `no_support`: Providers that do not work with Geyser. + +To add a new provider, add an object to the appropriate subcategory in alphabetical order. For example, to add a provider named `Example Hosting Provider` to the `supported` subcategory, edit the `providers.ts` file as follows: + +```diff + { + name: 'Cubes Hosting', + url: 'https://www.cubes.host/', + description: translate({ + id: 'providers.provider.cubes_hosting.description', + message: "Install Geyser using the plugin manager. Then restart the server and Geyser will run on an additional port - you can check it in the server console. Geyser-Standalone can be set up through a support ticket." + }) + }, ++ { ++ name: 'Example Hosting Provider', ++ url: 'https://example.com/', ++ description: translate({ ++ id: 'providers.provider.example_hosting_provider.description', ++ message: "Add a description of how to install Geyser on this hosting provider." ++ }) ++ }, + { + name: 'exaroton', + url: 'https://exaroton.com/', + description: translate({ + id: 'providers.provider.exaroton.description', + message: descriptionTemplates.default + }) + }, +``` + +If possible, use one of the templates listed at the top of the file, such as `descriptionTemplates.default`. + +## Creating a New Page + +All documentation is in the `docs` folder, where you can add new pages or edit the current ones. When a new page is added, it must also be added to [sidebar.ts](sidebar.ts). Pages that are written in plain markdown should use the extension `.md`, while pages that include React components should use the extension `.mdx`. + +### Example Page Layout ```md --- title: Page title -page_sidebar: false (optional) +description: A short description of the page. --- -# Page title +## Page Subheading One {#page-subheading-1} + This is an example page. + +## Page Subheading Two {#page-subheading-2} + +This is more of an example page. ``` -### Adding page to the sidebar +### Adding a Page to the Sidebar -Once you have added the file you can add a sidebar link. All sidebar links + sub links are in the _data/toc.yml file. +Once you have added the file you can add a sidebar link. All sidebar links and categories are defined in the [`sidebar.ts`](sidebar.ts) file. -### Example sidebar structure +Simply add the page to the items section of the appropriate category. For example, to add a page about an advanced configuration created at the file `docs/geyser/advanced-configuration.md`, edit the `sidebar.ts` as follows: -``` -- title: Page Title Documentation - url: "page/" - links: - - title: "Pagetitle sub link" - url: "page/pagetitle/" - children: - - title: PageChild sub link - url: "page/pagetitle/#headerLink" +```diff +{ + type: 'category', + label: 'Configuring Geyser', + link: { + type: 'doc', + id: 'geyser/understanding-the-config', + }, + items: [ + 'geyser/commands', + 'geyser/translations', + 'geyser/geyser-command-line-arguments-and-system-properties', ++ 'geyser/advanced-configuration', + ] +}, ``` -### GeyserWiki development - Local deployment on Windows. +## Running the Website Locally -* Download and install Ruby using the Ruby+Devkit from https://rubyinstaller.org/downloads/. +### Dependencies -* Once installed, run 'ridk install' in console to open the RubyInstaller. -For this usecase, it is recommended to choose the third option, "MSYS and MINGW". After that, the Ruby installation is completed. +#### Windows -* Open the GeyserWiki folder in VScode. There, open a terminal to install the bundle using the 'bundle install' command. -Installing it for the first time can take a while. +Open PowerShell and run: -* Once installed, you can start the webserver locally with the 'bundle exec jekyll serve' command in the VSC terminal. +```ps1 +winget install -e --id OpenJS.NodeJS +winget install -e --id Yarn.Yarn +winget install -e --id Git.Git +``` + +#### macOS + +First, install [Homebrew](https://brew.sh/) if not already installed by opening Terminal and running: + +```bash +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" +``` + +Then, open a new Terminal window and run to install the dependencies: + +```bash +brew install node +brew install yarn +brew install git +``` + +#### Linux + +Install [Node.js](https://nodejs.org/en/download/package-manager/), [Yarn](https://classic.yarnpkg.com/en/docs/install), and [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) using the package manager for your distribution. + +### Running + +```sh +git clone https://github.com/GeyserMC/GeyserWebsite +cd GeyserWebsite +yarn +yarn start +``` + +This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. \ No newline at end of file diff --git a/README.md b/README.md index aaba2fa..828b01e 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,42 @@ # Website -This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator. +This is the Geyser website is built using [Docusaurus 3](https://docusaurus.io/). -### Installation +## Contributing -``` -$ yarn -``` +See [CONTRIBUTING.md](CONTRIBUTING.md) for more information. -### Local Development +## Project Structure -``` -$ yarn start -``` +- [`blog/`](/blog/): Blog markdown files +- [`docs/`](/docs/): Wiki markdown files + - [`api/`](/docs/api/): Rest API documentation + - [`floodgate/`](/docs/floodgate/): Floodgate documentation + - [`geyser/`](/docs/geyser): Geyser documentation + - [`other/`](/docs/other/): Other projects documentation +- [`i18n/`](/i18n/): Translations for the website +- [`openapi/`](/openapi/): OpenAPI spec files to auto-generate REST API documentation +- [`src/`](/src/): Source of the website + - [`components/`](/src/components/): React components + - [`css/`](/src/css/): Styles + - [`data/`](/src/data/): Data files, such as hosting providers and supported Minecraft versions + - [`pages/`](/src/pages/): Pages of the website + - [`renderer/`](/src/renderer/): Renderer for thumbnails + - [`theme/`](/src/theme/): Overrides base Docusaurus theme, such as importing fa icons + - [`types/`](/src/types/): TypeScript types +- [`static/`](/static/): Static content + - [`img/`](/static/img/): Images +- [`docusaurus.config.ts`](/docusaurus.config.ts): Docusaurus configuration file +- [`package.json`](/package.json): Node.js project file +- [`sidebar.ts`](/sidebar.ts): Site sidebar configuration +- [`tsconfig.json`](/tsconfig.json): TypeScript configuration file +- [`yarn.lock`](/yarn.lock): Yarn lock file for Node.js dependencies -This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. +## Quick Start -### Build - -``` -$ yarn build -``` - -This command generates static content into the `build` directory and can be served using any static contents hosting service. - -### Deployment - -Using SSH: - -``` -$ USE_SSH=true yarn deploy -``` - -Not using SSH: - -``` -$ GIT_USER= yarn deploy -``` - -If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch. +```sh +git clone https://github.com/GeyserMC/GeyserWebsite +cd GeyserWebsite +yarn +yarn start +``` \ No newline at end of file diff --git a/docs/geyser/custom-blocks.md b/docs/geyser/custom-blocks.md index a33547f..cb3a881 100644 --- a/docs/geyser/custom-blocks.md +++ b/docs/geyser/custom-blocks.md @@ -1,10 +1,8 @@ --- -title: Custom blocks with Geyser +title: Custom Blocks description: Geysers allows custom blocks to be mapped to Vanilla Java blockstates or modded blocks to allow custom block models. --- -# Custom blocks with Geyser - To setup custom blocks in geyser, you have to choose how you are going to register your blocks. The easiest is [using a json file](#json-mappings) but you can also [use a Geyser extension](#geyser-extensions). It should be noted that blocks and their associated components are not very stable. Mojang tends to make changes to these much more often than they do for items. This means that any components Geyser allows you to register are liable to break in future versions of Bedrock. diff --git a/docs/geyser/custom-items.md b/docs/geyser/custom-items.md index 571834e..0cdaf80 100644 --- a/docs/geyser/custom-items.md +++ b/docs/geyser/custom-items.md @@ -1,10 +1,8 @@ --- -title: Custom items with Geyser +title: Custom Items description: Geyser allows custom Bedrock items to be added for an equivalency to Vanilla Java item predicates or modded items. --- -# Custom items with Geyser - To setup custom items in geyser, you have to choose how you are going to register your items. The easiest is [using a json file](#json-mappings) but you can also [use a Geyser extension](#geyser-extensions). ## JSON mappings {#json-mappings} diff --git a/docs/geyser/custom-resource-packs.md b/docs/geyser/custom-resource-packs.md new file mode 100644 index 0000000..8d7522c --- /dev/null +++ b/docs/geyser/custom-resource-packs.md @@ -0,0 +1,9 @@ +--- +title: Custom Resource Packs +description: How to use custom resource packs for Geyser. +--- + +Geyser supports custom resource packs for use with custom items, blocks, and skulls. See: +- [Custom items](/geyser/custom-items) +- [Custom blocks](/geyser/custom-blocks) +- [Custom skulls](/geyser/custom-skulls) \ No newline at end of file diff --git a/docs/geyser/custom-skulls.md b/docs/geyser/custom-skulls.md index 52cd219..36c36c7 100644 --- a/docs/geyser/custom-skulls.md +++ b/docs/geyser/custom-skulls.md @@ -1,10 +1,8 @@ --- -title: Custom skulls with Geyser +title: Custom Skulls description: Geyser allows mapping of custom skulls to custom blocks for use in inventories and on entities. --- -# Custom skulls with Geyser - Unlike Java Edition, Bedrock does not have native support for custom skull items. As a result, any method to display custom skulls with Geyser is, to some extent, a workaround. Geyser has long supported in-world custom skulls via the spawning of player entities. This, however, does not allow for the use of custom skulls in inventories, nor does it allow them to be worn by entities. To resolve this, Geyser now allows for the pre-registration of custom skulls via a config file. Geyser will then use this config file to generate a custom resource pack on start that contains the geometry and textures for the pre-registered custom skulls. To the client, these skulls are blocks. Therefore, they can be held in player inventories. In additional, attachables are defined for each skull block so that it is displayed correctly when worn and held by entities. To setup custom skulls in geyser, you have to choose how you are going to register your blocks. The easiest is [using custom-skulls.yml](#custom-skullsyml), but you can also [use a Geyser extension](#geyser-extensions). diff --git a/sidebars.ts b/sidebars.ts index 4ebfb52..a1aaae5 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -89,9 +89,19 @@ const sidebars: SidebarsConfig = { 'geyser/current-limitations' ] }, - 'geyser/custom-items', - 'geyser/custom-blocks', - 'geyser/custom-skulls', + { + type: 'category', + label: 'Custom Resource Packs', + link: { + type: 'doc', + id: 'geyser/custom-resource-packs' + }, + items: [ + 'geyser/custom-items', + 'geyser/custom-blocks', + 'geyser/custom-skulls', + ] + }, { type: 'category', label: 'Geyser API',