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

astro.config.ts

@@ -323,6 +323,7 @@ export default defineConfig({
                       label: "Getting started",
                       items: [
                         "velocity/dev/creating-your-first-plugin",
+                        "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">
@@ -71,6 +80,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 +96,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 +125,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 +168,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,115 @@
+---
+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. 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/
+    - 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", // required
+  "name": "Velocity Example Plugin",
+  "version": "1.0.0",
+  "description": "An example plugin for showcasing the plugin json file.",
+  "main": "com.example.testplugin.TestPluginMain", // required
+  "url": "https://github.com/PaperMC/docs",
+  "authors": ["Strokkur24"],
+  "dependencies": [
+    {
+      "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
+      }
+    ]
+  }
+  ```