feat: add name/id documentation, made example use all fields, replace field headers with list entries, move sidebar entry, add note inside creating-your-first-plugin

Author: Strokkur424

astro.config.ts

@@ -323,8 +323,8 @@ export default defineConfig({
                       label: "Getting started",
                       items: [
                         "velocity/dev/creating-your-first-plugin",
-                        "velocity/dev/api-basics",
                         "velocity/dev/velocity-plugin-json",
+                        "velocity/dev/api-basics",
                         "velocity/dev/pitfalls",
                       ],
                     },

src/content/docs/velocity/dev/getting-started/creating-your-first-plugin.mdx

@@ -57,6 +57,15 @@ How to set up a build system is outside the scope of this page, but you can look
 system's documentation ([Gradle](https://docs.gradle.org/current/userguide/userguide.html) or
 [Maven](https://maven.apache.org/guides/getting-started/index.html)) for assistance.
 
+:::info[velocity-plugin.json]
+
+Before you set up your build system, you should think about whether you want your `velocity-plugin.json`
+to be generated automatically using a `@Plugin` annotation in your source code or if you want to write it
+manually. Depending on which you prefer, you may need to add additional lines to your build files. You can find
+more information on the [`velocity-plugin.json`] file [here](/velocity/dev/velocity-plugin-json).
+
+:::
+
 ### Setting up the dependency
 
 <Tabs syncKey="build-system">

src/content/docs/velocity/dev/getting-started/velocity-plugin-json.mdx

@@ -7,10 +7,9 @@ slug: velocity/dev/velocity-plugin-json
 import { FileTree } from "@astrojs/starlight/components";
 
 The `velocity-plugin.json` file is the configuration file for your plugin. It contains information
-about your plugin's name, description, version, main class path, and other.
-
-The `velocity-plugin.json` file is located in the `resources` directory of your plugin. It is generated
-automatically if you configured the Velocity annotation processor and used the `@Plugin` annotation.
+about your plugin's name, description, version, main class path, and other. It is located in the `resources`
+directory of your plugin and may be generated automatically, if you configured the Velocity annotation processor
+and used a `@Plugin` annotation somewhere in your code.
 
 <FileTree>
   - velocity-plugin/
@@ -28,62 +27,89 @@ This is an example `velocity-plugin.json` file:
 
 ```json title=velocity-plugin.json
 {
-  "id": "example-plugin",
+  "id": "example-plugin", // required
   "name": "Velocity Example Plugin",
   "version": "1.0.0",
   "description": "An example plugin for showcasing the plugin json file.",
-  "main": "com.velocitypowered.testplugin.TestPluginMain"
-}
-```
-
-## Fields
-The only required fields are `id` and `main`. Any other fields are optional.
-
-### id
-The ID of the plugin. This ID needs to be unique for each plugin.
-- `"id": "a_cool_plugin"`
-
-Plugin IDs must start with a lowercase letter and may contain lowercase letters,
-digits, hyphens, and underscores. The total length must not exceed 64 characters.
-
-### main
-The path towards your main plugin class.
-- `"main": "com.example.yourplugin.PluginMain"`
-
-### name
-A user-friendly variant of your plugin's name.
-- `"name": "A cool plugin"`
-
-### version
-The version of your plugin.
-- `"version": "0.0.1-beta.7"`
-
-### description
-The description of your plugin.
-- `"description": "Some interesting plugin description."`
-
-### url
-The URL of your plugin's website.
-- `"url": "https://github.com/PaperMC/Velocity"`
-
-### authors
-A list of your plugin's authors.
-- `"authors": ["Strokkur24", "electronicboy"]`
-
-### dependencies
-Your plugin's dependencies. The value of this field is an array of dependency objects.
-
-The dependency object itself has two fields:
-- `id` the plugin ID of the plugin you depend upon
-- `optional` whether the dependency is optional. This field is not required and defaults to `false`.
-
-```json
-{
+  "main": "com.example.testplugin.TestPluginMain", // required
+  "url": "https://github.com/PaperMC/docs",
+  "authors": ["Strokkur24"],
   "dependencies": [
     {
-      "id": "luckperms",
-      "optional": true
+      "id": "luckperms", // required for dependencies
+      "optional": true // defaults to false
     }
   ]
 }
 ```
+
+## Fields
+The only required fields are `id` and `main`. Any other fields are optional.
+
+- **`id`**\
+  The ID of the plugin. This ID needs to be unique for each plugin. It is used for identifying your
+  plugin internally and also used as the name for your plugin's logger.
+
+  Plugin IDs must start with a lowercase letter and may contain lowercase letters,
+  digits, hyphens, and underscores. The total length must not exceed 64 characters.
+
+  ```json
+  {"id": "a_cool_plugin"}
+  ```
+
+- **`main`**\
+  The path towards your main plugin class.
+
+  ```json
+  {"main": "com.example.yourplugin.PluginMain"}
+  ```
+
+- **`name`**\
+  A user-friendly variant of your plugin's name. This is used for any user-facing display of your plugin, such
+  as the `/velocity plugins` command.
+
+  ```json
+  {"name": "A cool plugin"}
+  ```
+
+- **`version`**\
+  The version of your plugin.
+  ```json
+  {"version": "0.0.1-beta.7"}
+  ```
+
+- **`description`**\
+  The description of your plugin.
+  ```json
+  {"description": "Some interesting plugin description."}
+  ```
+
+- **`url`**\
+  The URL of your plugin's website.
+  ```json
+  {"url": "https://github.com/PaperMC/Velocity"}
+  ```
+
+- **`authors`**\
+  A list of your plugin's authors.
+  ```json
+  {"authors": ["Strokkur24", "electronicboy"]}
+  ```
+
+- **`dependencies`**\
+  Your plugin's dependencies. The value of this field is an array of dependency objects.
+
+  The dependency object itself has two fields:
+  - `id` the plugin ID of the plugin you depend upon
+  - `optional` whether the dependency is optional. This field is not required and defaults to `false`.
+
+  ```json
+  {
+    "dependencies": [
+      {
+        "id": "luckperms",
+        "optional": true
+      }
+    ]
+  }
+  ```