feat(velocity): document velocity-plugin.json file

astro.config.ts

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

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

@@ -71,6 +71,7 @@ system's documentation ([Gradle](https://docs.gradle.org/current/userguide/userg
 
     dependencies {
       compileOnly("com.velocitypowered:velocity-api:\{LATEST_VELOCITY_RELEASE}")
+      // If you want your velocity-plugin.json file to be generated based on plugin annotations
       annotationProcessor("com.velocitypowered:velocity-api:\{LATEST_VELOCITY_RELEASE}")
     }
     ```
@@ -86,6 +87,7 @@ system's documentation ([Gradle](https://docs.gradle.org/current/userguide/userg
 
     dependencies {
       compileOnly 'com.velocitypowered:velocity-api:\{LATEST_VELOCITY_RELEASE}'
+      // If you want your velocity-plugin.json file to be generated based on plugin annotations
       annotationProcessor 'com.velocitypowered:velocity-api:\{LATEST_VELOCITY_RELEASE}'
     }
     ```
@@ -114,7 +116,7 @@ system's documentation ([Gradle](https://docs.gradle.org/current/userguide/userg
           <version>\{LATEST_VELOCITY_RELEASE}</version>
           <scope>provided</scope>
         </dependency>
-        <!-- add the annotation processor -->
+        <!-- add the annotation processor if you want your velocity-plugin.json file to be generated -->
         <dependency>
           <groupId>com.velocitypowered</groupId>
           <artifactId>velocity-api</artifactId>
@@ -157,7 +159,7 @@ system's documentation ([Gradle](https://docs.gradle.org/current/userguide/userg
             <groupId>org.apache.maven.plugins</groupId>
             <artifactId>maven-compiler-plugin</artifactId>
             <configuration>
-              <!-- add the annotation processor -->
+              <!-- add the annotation processor if you want your velocity-plugin.json file to be generated -->
               <annotationProcessorPaths>
                 <path>
                   <groupId>com.velocitypowered</groupId>

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

@@ -0,0 +1,90 @@
+---
+title: The Velocity plugin file
+description: A full reference of the velocity-plugin.json file.
+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.
+
+<FileTree>
+  - velocity-plugin/
+    - src/
+      - main/
+        - java/
+        - resources/
+          - **velocity-plugin.json**
+    - build.gradle.kts
+    - settings.gradle.kts
+</FileTree>
+
+## Example
+This is an example `velocity-plugin.json` file:
+
+```json title=velocity-plugin.json
+{
+  "id": "example-plugin",
+  "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 three fields:
+- `id` the plugin ID of the plugin you depend upon
+- `version` the version of your dependency. This field is not required.
+- `optional` whether the dependency is optional. This field is not required. Defaults to `false`.
+
+```json
+{
+  "dependencies": [
+    {
+      "id": "luckperms",
+      "optional": true
+    }
+  ]
+}
+```