External Documentation (LunarClient#856)

* feat: start external documentation

* fix: can't use cool shared workflow

* chore: start docs structure

* chore: more docs

* backgrounds

* Updated Intro

* Add copyright Callout

* Update banner.mdx

* Update logo.mdx

* Update overview

* Fix typos

* finish up documentation/README

* call out?

* fix: file whitelist

* Fix typo

* Fix typo

* banner docs

* make banners max be 15 seconds

---------

Co-authored-by: Trentin <[email protected]>

Author: imconnorngl

.github/CODEOWNERS

@@ -2,4 +2,4 @@
 /.github/** @colinmcdonald22 @imconnorngl @ThatKawaiiSam
 
 # Script changes
-/scripts/* @colinmcdonald22 @imconnorngl @ThatKawaiiSam
+/.scripts/* @colinmcdonald22 @imconnorngl @ThatKawaiiSam

.github/workflows/docs.yml

@@ -0,0 +1,24 @@
+name: Deploy Documentation
+on:
+  push:
+    paths:
+      - ".github/workflows/docs.yml"
+      - "docs/**"
+
+jobs:
+  deploy:
+    name: Deploy Documentation
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - name: Trigger Documentation Deploy
+        uses: benc-uk/workflow-dispatch@v1
+        with:
+          workflow: deploy.yml
+          repo: LunarClient/lunarclient.dev-Build
+          ref: refs/heads/master
+          inputs: '{"repo": "${{ github.repository }}", "ref": "${{ github.ref }}", "sha": "${{ github.sha }}"}'
+          token: ${{ secrets.DISPATCH_TOKEN }}

.github/workflows/ping-servers.yml

@@ -3,7 +3,7 @@ name: Ping Servers
 on:
   push:
     branches:
-    - master
+      - master
   workflow_dispatch:
 
 jobs:
@@ -17,10 +17,10 @@ jobs:
       - name: Setup Python 3.x
         uses: actions/setup-python@v1
         with:
-          python-version: '3.x'
+          python-version: "3.x"
 
       - name: Install Python dependencies
-        run: pip install -r scripts/requirements.txt
+        run: pip install -r .scripts/requirements.txt
 
       - name: Validate Server Status
-        run: python scripts/validate_status.py --servers_dir servers --inactive_file inactive.json
+        run: python .scripts/validate_status.py --servers_dir servers --inactive_file inactive.json

.github/workflows/validate-upload.yml

@@ -3,11 +3,10 @@ name: Validate and upload
 on:
   push:
     branches:
-    - master
+      - master
   pull_request:
     branches:
-    - master
-
+      - master
 
 jobs:
   validate-servers:
@@ -23,13 +22,13 @@ jobs:
       - name: Setup Python 3.x
         uses: actions/setup-python@v1
         with:
-          python-version: '3.x'
+          python-version: "3.x"
 
       - name: Install Python dependencies
-        run: pip install -r scripts/requirements.txt
+        run: pip install -r .scripts/requirements.txt
 
       - name: Validate Servers
-        run: python scripts/validate.py --servers_dir servers --metadata_schema metadata.schema.json --inactive_file inactive.json --inactive_schema inactive.schema.json
+        run: python .scripts/validate.py --servers_dir servers --metadata_schema metadata.schema.json --inactive_file inactive.json --inactive_schema inactive.schema.json
         env:
           PR_ID: ${{ github.event.pull_request.number }}
           BOT_PAT: ${{ secrets.GITHUB_TOKEN }}
@@ -40,7 +39,7 @@ jobs:
     if: github.event_name == 'push' && github.ref == 'refs/heads/master'
 
     runs-on: ubuntu-latest
-    
+
     permissions:
       id-token: write
       contents: read
@@ -52,21 +51,21 @@ jobs:
       - name: Setup Python 3.x
         uses: actions/setup-python@v1
         with:
-          python-version: '3.x'
+          python-version: "3.x"
 
       - name: Install Python dependencies
-        run: pip install -r scripts/requirements.txt
+        run: pip install -r .scripts/requirements.txt
 
       - name: Create output folder
         run: mkdir .out/
-          
+
       - name: Output Server Media
-        run: python scripts/convert_media.py --servers_dir servers --inactive_file inactive.json --servers_logos_output .out/logos --servers_logos_sizes 256 128 64 32 --servers_backgrounds_output .out/backgrounds --servers_backgrounds_sizes 1280x720 852x480 --servers_banners_output .out/banners
+        run: python .scripts/convert_media.py --servers_dir servers --inactive_file inactive.json --servers_logos_output .out/logos --servers_logos_sizes 256 128 64 32 --servers_backgrounds_output .out/backgrounds --servers_backgrounds_sizes 1280x720 852x480 --servers_banners_output .out/banners
         env:
           USE_ARGS: "true"
 
       - name: Create Index File
-        run: python scripts/create_index.py --servers_dir servers --inactive_file inactive.json --index_output .out/servers.json
+        run: python .scripts/create_index.py --servers_dir servers --inactive_file inactive.json --index_output .out/servers.json
 
       - name: Upload to Cloudflare
         env:

scripts/convert_media.py .scripts/convert_media.py

@@ -1,5 +1,5 @@
-Pillow
-webptools
-jsonschema
-mcstatus
+Pillow
+webptools
+jsonschema
+mcstatus
 requests

scripts/create_index.py .scripts/create_index.py

@@ -190,23 +190,14 @@ def validate_banner(path, server_name):
         # loop through all the frames, rather than just do duration * n_frames, because GIF can have different duration for each frame.
         for idx in range(1, banner_image.n_frames):
             banner_image.seek(idx)
-            #if banner_image.info['duration'] != duration:
-            #    errors.append(f'{server_name}\'s server banner does not have the same duration for all frames... Please ensure the image meets the requirements before proceeding.')
-
             total_duration += duration
 
-        #if total_duration > 10000:
-        #    errors.append(f'{server_name}\'s server banner is more than 10 seconds long (currently {total_duration / 1000})... Please ensure the image meets the requirements before proceeding.')
+        if total_duration > 15_000:
+           errors.append(f'{server_name}\'s server banner is more than 15 seconds long (currently {total_duration / 1000})... Please ensure the image meets the requirements before proceeding.')
 
         if total_duration == 0:
             errors.append(f'{server_name}\'s server gif server banner seems to not have any duration associated with it... Please ensure the image meets the requirements before proceeding.')
 
-        # TODO: some sort of fix so only one of the errors above or below show ( temp atm )
-        #fps = (banner_image.n_frames / (total_duration / 1000.0)) if total_duration != 0 else 20.0
-
-        #if fps != 20.0:
-        #    errors.append(f'{server_name}\'s server banner is not exactly 20 FPS (currently {fps})... Please ensure the image meets the requirements before proceeding.')
-
     aspect_ratio = round(banner_image.width / banner_image.height, 3)
 
     sprite = gif_to_sprite_sheet(path)

scripts/requirements.txt .scripts/requirements.txt

@@ -6,7 +6,7 @@
 
 from utils import get_all_servers, validate_logo, validate_background, validate_banner
 
-file_whitelist = ['.git', '.github', '.gitignore', 'inactive.json', 'inactive.schema.json', 'LICENSE', 'metadata.example.json', 'metadata.schema.json', 'README.md', 'scripts', 'servers']
+FILE_WHITELIST = ['.git', '.github', '.gitignore', 'inactive.json', 'inactive.schema.json', 'LICENSE', 'metadata.example.json', 'metadata.schema.json', 'README.md', '.scripts', 'servers', 'docs']
 
 def post_comment(messages: dict):
     pull_id = os.getenv('PR_ID')
@@ -176,9 +176,9 @@ def check_media(args: argparse.Namespace, current_errors: dict) -> dict:
 
 
 def validate_root(dir="."):
-    if any([file not in file_whitelist for file in os.listdir(dir)]):
-            post_comment({"Overall": ["A file is in the main directory but not in file_whitelist"]})
-            print("A file is in the main directory but not in file_whitelist")
+    if any([file not in FILE_WHITELIST for file in os.listdir(dir)]):
+            post_comment({"Overall": ["A file is in the main directory but not in file whitelist"]})
+            print("A file is in the main directory but not in file whitelist")
             exit(1)
 
 if __name__ == '__main__':

scripts/utils.py .scripts/utils.py

@@ -2,71 +2,32 @@
 
 ## Summary
 
-This is a public mapping of server IPs <-> a pretty display name. This data is used extensively around Lunar Client, most notably when displaying server names (or "Private Server", if unknown) on the friends list. Historically, this mapping was handled internally, and server owners did not have a good way to manage data for their server.
+Server Mappings is a collection of mappings for Minecraft servers, including the most popular servers such as Hypixel, Mineplex, and more. Server Mappings provides information such as server name, server icon and more.
 
-## How do I add/update/remove a server?
-
-Each server in ServerMappings is represented by a folder with an accompanying `metadata.json` and `logo.png`. Open a pull request in this repository whilst following the steps below, and we'll review it as soon as possible. Once merged, Lunar Client services will update over the next 20 minutes. Check out `metadata.example.json` as an example of how to structure your metadata file.
-
-## IP Addresses
-
-The `addresses` array in each server object is actually an array of IP _suffixes_. For example, `"addresses": ["lunar.gg", "other.domain"]` will match `lunar.gg`, `na.lunar.gg`, `play.other.domain`, and so on. The `primaryAddress` field is where you can include the desired subdomain (`na.lunar.gg`, `play.lunar.gg`) for users to connect to your server on and is required to be resolvable. This primary address will be used to ensure that the server remains online and active.
-
-## Primary Info & Minecraft Versions
-
-We also require your server's primary connection information and allowed client versions. The `primaryAddress` field should be an address included** in the `addresses` array.
-
-The `minecraftVersions` field must be an array of client versions allowed on your Minecraft server. *(ie. 1.18.1, 1.19.2)*; The `primaryMinecraftVersion` field must be a subversion of a major version included in the `minecraftVersions` array. **The versions you include must be versions that are directly offered in Lunar Client**, which can be found in the version selector of the Lunar Client Launcher.
-
-If your server supports all of the subversions within a major version, you can list the version in `minecraftVersions` as `1.19.*`, but you will still need to specify the specific subversion in the `primaryMinecraftVersion` as this is the specific version that the client uses to Launch you into the game for Quick Joining.
-
-## Logos
-
-In addition to the data that you will need to provide in your `metadata.json`, you will need to upload a `.png` version of your logo into the same folder. All images are to be _transparent_, _square (1:1 aspect ratio)_, and _a minimum of 512px in width and height_. The file name should be `logo.png`. We require the logo to be large as we perform a number of different transformations for all the various places in Lunar Client!
-
-## Backgrounds
+For a full overview of the information which can be found in Server Mappings, [check out our documentation](https://lunarclient.dev/server-mappings/introduction).
 
-Servers are also required to provide background image, you will need to upload a `.png` version of the background into the same folder as your `metadata.json`. Images should represent either the artistic style or the content of the server, with images needing to be _a minimum of 1920px in width and 1080px in height, resulting in a 16:9 aspect ratio_. The file name should be `background.png`. Backgrounds should be free of marketing, text, and/or any logos (that isn't part of a build).
-
-## Banners
-
-Servers may also provide a server banner - you will be made aware if this is a requirement for your server. If a banner is provided, it must be uploaded as either a `.png` version named `banner.png` (for static banners,) or a `.gif` version named `banner.gif` (for animated banners,) in the same folder as your `metadata.json`. Banners should represent the content of the server, and prominently feature the server's name and/or IP. All banners must be _a minimum of 340 pixels wide and 45 pixels high, resulting in a 68:9 aspect ratio._ Additionally, animated (GIF) banners must play at _20 frames per second_, and be no more than _10 seconds in duration_.
-
-## Regions
-
-In your `metadata.json`, you can define both a `primaryRegion` and `regions` which your server supports. Below is a table of the regions.
-
-| Region Code | Name |
-| --- | --- |
-| AF | Africa |
-| AS | Asia |
-| EU | Europe |
-| NA | North America |
-| OC | Oceania |
-| SA | South America |
-
-## Game Types
-
-Game types help identify the style of games that your server will offer to player. The following are games you may include: `PvP`, `PvE`, `HCF`, `Factions`, `Minigames`, `Skyblock`, `Parkour`, `UHC`, `Hardcore`, `Survival`, `Open World`, `Prison`, `Creative`, `Roleplay`, and `Adventure`.
+## How do I add/update/remove a server?
 
-You can add up to 3 unique types on the `gameTypes` field in your `metadata.json`.
+You can add your server to Server Mappings by creating a pull request on this repository. We ask that you **must** follow the guidelines detailed in [our documentation](https://lunarclient.dev/server-mappings/adding-servers/overview) on what you should include to have your server added.
 
 ## Restrictions
 
 We ask that this repository is only used to store mappings for *public* Minecraft servers. Some server IPs, such as private SMPs, tournament servers, etc. should not be listed in this repository, out of respect for privacy.
 
-Lunar Client also reserves the right to omit any servers that do not comply with our [Terms of Service](https://www.lunarclient.com/terms).
+**Lunar Client also reserves the right to omit any servers that do not comply with our [terms of service](https://www.lunarclient.com/terms).**
+
 
 ## Inactive Server Policy
 
 If a server has closed down or has not been joinable for at least 3 months, we will add it to the `inactive.json`. This just flags our internal systems to not include the server in various place, but still retains all of the branding and other metadata you submit.
 
-If you think your server has been added to this list by mistake, please make a support ticket at the link below.
+If you believe your server has been incorrectly marked as inactive, please contact us in the [Lunar Client Developers Discord](https://discord.gg/ww4UhsPNwf) or [create an issue](https://github.com/LunarClient/ServerMappings/issues/new).
+
+## Can I use this data for my project?
 
-## Can I use this data for ___?
+You are free to use this data for anything you wish. As long as it abides by [our terms of service](https://www.lunarclient.com/terms). You can read how to harness this data in our [documentation](https://lunarclient.dev/server-mappings/using-servermappings).
 
-Go for it!
 
 ## Any other questions?
 
-Please contact us at [support.lunarclient.com](https://support.lunarclient.com) for any additional questions.
+Please join our [Lunar Client Developers Discord](https://discord.gg/ww4UhsPNwf) for any additional questions.

scripts/validate.py .scripts/validate.py

@@ -0,0 +1,6 @@
+{
+    "introduction": "Introduction",
+    "adding-servers": "Adding Servers",
+    "using-servermappings": "Using Server Mappings",
+    "inactive-servers": "Inactive Servers"
+}

scripts/validate_status.py .scripts/validate_status.py

@@ -0,0 +1,7 @@
+{
+    "overview": "Overview",
+    "metadata": "Metadata",
+    "logo": "Logo",
+    "background": "Background",
+    "banner": "Banner"
+}

README.md

@@ -0,0 +1,18 @@
+import { Callout } from "nextra/components";
+
+# Server Background
+
+<Callout type="warning" emoji="⚠️">
+  Do not include any copyrighted or proprietary graphics without written
+  permission or ownership.
+</Callout>
+
+Servers are required to provide a background image. Please note the following requirements for the background image:
+
+- The background image should be in the `.png` format.
+- The image should represent either the artistic style or the content of the server.
+- The minimum dimensions for the background image are `1920px` in width and `1080px` in height, resulting in a 16:9 aspect ratio.
+- The file name should be `background.png`.
+- The background image should be free of marketing, text, and any logos that are not part of the server build.
+
+Please ensure that your background image meets these requirements. Remember that your background image will be manually reviewed before being accepted.

docs/_meta.json

@@ -0,0 +1,18 @@
+import { Callout } from "nextra/components";
+
+# Server Banner
+
+<Callout type="warning" emoji="⚠️">
+  Do not include any copyrighted or proprietary graphics without written
+  permission or ownership.
+</Callout>
+
+Servers may also provide a server banner. If it is required for your server, please take note of the following guidelines:
+
+- If a static banner is provided, it should be uploaded as a `.png` version named `banner.png`.
+- If an animated banner is provided, it should be uploaded as a `.gif` version named `banner.gif`.
+- The banner should represent the content of the server and prominently feature the server's name and/or IP.
+- All banners must have a minimum width of `340` pixels and a height of `45` pixels, resulting in a 68:9 aspect ratio.
+- Animated (GIF) banners must not exceed a total duration of 15 seconds.
+
+Please ensure that your server banner meets these requirements. As with other assets, the server banner will be reviewed before being accepted.

docs/adding-servers/_meta.json

@@ -0,0 +1,18 @@
+import { Callout } from "nextra/components";
+
+# Server Logo
+
+<Callout type="warning" emoji="⚠️">
+  Do not include any copyrighted or proprietary graphics without written
+  permission or ownership.
+</Callout>
+
+For your server to be included in Server Mappings, your server will need to include a logo, this logo must:
+
+- Be in the `.png` format.
+- Be transparent.
+- Be square (1:1 aspect ratio).
+- Be a minimum of `512px` in width and height
+- Not be upscaled from a smaller low quality image
+
+_Your logo will be manually reviewed before being accepted. Please ensure it meets these requirements._