feat: some Paper dev pages

astro.config.ts

@@ -4,7 +4,7 @@ import { defineConfig } from "astro/config";
 import starlightSidebarTopics from "starlight-sidebar-topics";
 import codeConstantsPlugin from "./src/utils/remark/code_const";
 import javadocPlugin from "./src/utils/remark/javadoc";
-import { LATEST_PAPER_RELEASE, LATEST_VELOCITY_RELEASE } from "./src/utils/versions";
+import { LATEST_MC_RELEASE, LATEST_PAPER_RELEASE, LATEST_VELOCITY_RELEASE } from "./src/utils/versions";
 
 const prod = process.env.NODE_ENV === "production";
 
@@ -64,6 +64,30 @@ export default defineConfig({
                     { label: "Miscellaneous", autogenerate: { directory: "paper/admin/misc" } },
                   ],
                 },
+                {
+                  label: "Development",
+                  items: [
+                    {
+                      label: "Getting started",
+                      items: [
+                        "paper/dev/project-setup",
+                        "paper/dev/how-do-plugins-work",
+                        "paper/dev/getting-started/paper-plugins",
+                        "paper/dev/plugin-yml",
+                        "paper/dev/userdev",
+                      ],
+                    },
+                    {
+                      label: "Miscellaneous",
+                      items: [
+                        "paper/dev/using-databases",
+                        "paper/dev/debugging",
+                        "paper/dev/internals",
+                        "paper/dev/reading-stacktraces",
+                      ],
+                    },
+                  ],
+                },
                 {
                   label: "Contributing",
                   items: ["paper/contributing/events"],
@@ -147,9 +171,15 @@ export default defineConfig({
             },
           ],
           {
-            // pages excluded from sidebars
+            // pages excluded from sidebars - index.md(x) pages
             topics: {
-              paper: ["/paper/admin", "/paper/contributing"],
+              paper: [
+                "/paper/admin",
+                "/paper/dev",
+                "/paper/dev/getting-started",
+                "/paper/dev/misc",
+                "/paper/contributing",
+              ],
               velocity: ["/velocity/admin", "/velocity/dev"],
               folia: ["/folia/admin"],
               waterfall: ["/waterfall"],
@@ -176,6 +206,7 @@ export default defineConfig({
         codeConstantsPlugin,
         {
           constants: {
+            LATEST_MC_RELEASE,
             LATEST_PAPER_RELEASE,
             LATEST_VELOCITY_RELEASE,
           },

old/docs/paper/dev/getting-started/how-do-plugins-work.mdx → src/content/docs/paper/dev/getting-started/how-do-plugins-work.md

@@ -1,12 +1,9 @@
 ---
-slug: /dev/how-do-plugins-work
+title: How plugins work
 description: How plugins work in Paper.
+slug: paper/dev/how-do-plugins-work
 ---
 
-# How Plugins Work
-
-## Introduction
-
 Plugins are a way to extend the functionality of a Minecraft server. They are written in JVM-based languages such as
 Java, Kotlin, Groovy or Scala. Plugins are loaded from the `plugins` folder in the server directory. Plugins will be
 loaded from a `.jar` file.  Each plugin has a main class that is specified in the plugin's `plugin.yml` file. This
@@ -51,12 +48,12 @@ be done before the plugin is unloaded. This may include saving data to disk or c
 ## Event listeners
 
 Events are a way for plugins to listen to things that happen in the server and run code when they are fired. For
-example, <Javadoc name={"org.bukkit.event.player.PlayerJoinEvent"}>`PlayerJoinEvent`</Javadoc> is fired when a player
+example, [`PlayerJoinEvent`](jd:paper:org.bukkit.event.player.PlayerJoinEvent) is fired when a player
 joins the server. This is a more performant way to run code when something happens, as opposed to constantly checking.
 See our [event listener page](/paper/dev/event-listeners) for more.
 
 Some events are cancellable. This means that when the event is fired, it can be cancelled which negates or stops the
-effect of the event. For example, <Javadoc name={"org.bukkit.event.player.PlayerMoveEvent"}>`PlayerMoveEvent`</Javadoc>
+effect of the event. For example, [`PlayerMoveEvent`](jd:paper:org.bukkit.event.player.PlayerMoveEvent)
 is cancellable. This means that when it is cancelled, the player will not move. This is useful for things like anti-cheat,
 where you want to cancel the event if the player is moving too fast.
 
@@ -112,7 +109,7 @@ to run after 100 ticks - one second is 20 ticks during normal operation. It is i
 delayed if the server is lagging. For example, if the server is only running at 10 ticks per second, a task that is
 scheduled to run after 100 ticks will take 10 seconds.
 
-In Java, typically you could use <Javadoc name={"java.lang.Thread#sleep(long)"} project={"java"}>`Thread#sleep()`</Javadoc> to delay
+In Java, typically you could use [`Thread#sleep()`](jd:java:java.lang.Thread#sleep(long)) to delay
 the execution of code. However, if the code is running on the main thread, this will cause the server to pause for the
 delay. Instead, you should use the `Scheduler` API to schedule tasks to run later.
 Learn more about the `Scheduler` API [here](/paper/dev/scheduler).

src/content/docs/paper/dev/getting-started/index.md

@@ -0,0 +1,6 @@
+---
+title: Development guide
+---
+
+Welcome to the Paper development guide! This guide includes information and tutorials on
+how to start developing plugins for Paper.

old/docs/paper/dev/getting-started/paper-plugins.mdx → src/content/docs/paper/dev/getting-started/paper-plugins.md

@@ -1,10 +1,13 @@
 ---
-slug: /dev/getting-started/paper-plugins
+title: Paper plugins
 description: A development guide for how to write Paper-specific plugins.
+slug: paper/dev/getting-started/paper-plugins
+sidebar:
+  badge:
+    text: Experimental
+    variant: danger
 ---
 
-# Paper Plugins (Experimental)
-
 Paper plugins allow developers to take advantage of more modern concepts introduced by Mojang, such as datapacks, to
 expand the field of what the Paper API is able to introduce.
 
@@ -25,17 +28,15 @@ This will not act as a drop-in replacement for `plugin.yml`, as some things, as
 It should be noted that you still have the ability to include both `paper-plugin.yml` and `plugin.yml` in the same JAR.
 
 Here is an example configuration:
-<VersionFormattedCode language={"yaml"}>
-```
+```yaml replace
 name: Paper-Test-Plugin
 version: '1.0'
 main: io.papermc.testplugin.TestPlugin
 description: Paper Test Plugin
-api-version: '%%_MAJ_MIN_PAT_MC_%%'
+api-version: '\{LATEST_PAPER_RELEASE}'
 bootstrapper: io.papermc.testplugin.TestPluginBootstrap
 loader: io.papermc.testplugin.TestPluginLoader
 ```
-</VersionFormattedCode>
 
 ### Dependency declaration
 
@@ -110,20 +111,20 @@ has started by using [bootstrappers](#bootstrapper).
 
 ## Bootstrapper
 Paper plugins are able to identify their own bootstrapper by implementing
-<Javadoc name={"io.papermc.paper.plugin.bootstrap.PluginBootstrap"}>`PluginBootstrap`</Javadoc>
+[`PluginBootstrap`](jd:paper:io.papermc.paper.plugin.bootstrap.PluginBootstrap)
 and adding the class of your implementation to the bootstrapper field in the `paper-plugin.yml`.
 ```java title="TestPluginBootstrap.java"
 public class TestPluginBootstrap implements PluginBootstrap {
 
-    @Override
-    public void bootstrap(BootstrapContext context) {
+  @Override
+  public void bootstrap(BootstrapContext context) {
 
-    }
+  }
 
-    @Override
-    public JavaPlugin createPlugin(PluginProviderContext context) {
-        return new TestPlugin("My custom parameter");
-    }
+  @Override
+  public JavaPlugin createPlugin(PluginProviderContext context) {
+    return new TestPlugin("My custom parameter");
+  }
 
 }
 ```
@@ -132,36 +133,36 @@ Currently, bootstrappers do not offer much new API and are highly experimental.
 
 ## Loaders
 Paper plugins are able to identify their own plugin loader by implementing
-<Javadoc name={"io.papermc.paper.plugin.loader.PluginLoader"}>`PluginLoader`</Javadoc>
+[`PluginLoader`](jd:paper:io.papermc.paper.plugin.loader.PluginLoader)
 and adding the class of your implementation to the loader field in the `paper-plugin.yml`.
 
 The goal of the plugin loader is the creation of an expected/dynamic environment for the plugin to load into.
 This, as of right now, only applies to creating the expected classpath for the plugin, e.g. supplying external libraries to the plugin.
 ```java title="TestPluginLoader.java"
 public class TestPluginLoader implements PluginLoader {
 
-    @Override
-    public void classloader(PluginClasspathBuilder classpathBuilder) {
-        classpathBuilder.addLibrary(new JarLibrary(Path.of("dependency.jar")));
+  @Override
+  public void classloader(PluginClasspathBuilder classpathBuilder) {
+    classpathBuilder.addLibrary(new JarLibrary(Path.of("dependency.jar")));
 
-        MavenLibraryResolver resolver = new MavenLibraryResolver();
-        resolver.addDependency(new Dependency(new DefaultArtifact("com.example:example:version"), null));
-        resolver.addRepository(new RemoteRepository.Builder("paper", "default", "https://repo.papermc.io/repository/maven-public/").build());
+    MavenLibraryResolver resolver = new MavenLibraryResolver();
+    resolver.addDependency(new Dependency(new DefaultArtifact("com.example:example:version"), null));
+    resolver.addRepository(new RemoteRepository.Builder("paper", "default", "https://repo.papermc.io/repository/maven-public/").build());
 
-        classpathBuilder.addLibrary(resolver);
-    }
+    classpathBuilder.addLibrary(resolver);
+  }
 }
 ```
 Currently, you are able to add two different library types:
-<Javadoc name={"io.papermc.paper.plugin.loader.library.impl.JarLibrary"}>`JarLibrary`</Javadoc> and
-<Javadoc name={"io.papermc.paper.plugin.loader.library.impl.MavenLibraryResolver"}>`MavenLibraryResolver`</Javadoc>.
+[`JarLibrary`](jd:paper:io.papermc.paper.plugin.loader.library.impl.JarLibrary) and
+[`MavenLibraryResolver`](jd:paper:io.papermc.paper.plugin.loader.library.impl.MavenLibraryResolver).
 
 ## Differences
 
 ### Bukkit serialization system
 Paper plugins still support the serialization system (`org.bukkit.configuration.serialization`) that Bukkit uses. However, custom classes will not be
-automatically registered for serialization. In order to use <Javadoc name={"org.bukkit.configuration.ConfigurationSection#getObject(java.lang.String,java.lang.Class)"}>`ConfigurationSection#getObject`</Javadoc>,
-you **must** call <Javadoc name={"org.bukkit.configuration.serialization.ConfigurationSerialization#registerClass(java.lang.Class)"}>`ConfigurationSerialization#registerClass(Class)`</Javadoc>
+automatically registered for serialization. In order to use [`ConfigurationSection#getObject`](jd:paper:org.bukkit.configuration.ConfigurationSection#getObject(java.lang.String,java.lang.Class)),
+you **must** call [`ConfigurationSerialization#registerClass(Class)`](jd:paper:org.bukkit.configuration.serialization.ConfigurationSerialization#registerClass(java.lang.Class))
 before you attempt to fetch objects from configurations.
 
 ### Classloading isolation
@@ -187,7 +188,7 @@ See [declaring dependencies](#dependency-declaration) for more information on ho
 ### Commands
 Paper plugins do not use the `commands` field to register commands. This means that you do not need to include all
 of your commands in the `paper-plugin.yml` file. Instead, you can register commands using the
-[Brigadier Command API](../api/command-api/basics/introduction.mdx).
+[Brigadier Command API](/paper/dev/command-api/basics/introduction).
 
 ### Cyclic plugin loading
 

old/docs/paper/dev/getting-started/plugin-yml.mdx → src/content/docs/paper/dev/getting-started/plugin-yml.mdx

@@ -1,9 +1,10 @@
 ---
-slug: /dev/plugin-yml
-description: A guide to Bukkit's plugin.yml file.
+title: plugin.yml
+description: "A guide to Bukkit's plugin.yml file."
+slug: paper/dev/plugin-yml
 ---
 
-# Bukkit Plugin YML
+import { LATEST_PAPER_RELEASE } from "/src/utils/versions";
 
 The `plugin.yml` file is the main configuration file for your plugin.
 It contains information about your plugin, such as its name, version, and description.
@@ -25,17 +26,15 @@ example-plugin
 
 Here is an example of a `plugin.yml` file:
 
-<VersionFormattedCode language={"yaml"}>
-```
+```yaml replace
 name: ExamplePlugin
 version: 1.0.0
 main: io.papermc.testplugin.ExamplePlugin
 description: An example plugin
 author: PaperMC
 website: https://papermc.io
-api-version: '%%_MAJ_MIN_PAT_MC_%%'
+api-version: '\{LATEST_PAPER_RELEASE}'
 ```
-</VersionFormattedCode>
 
 ## Fields
 
@@ -92,8 +91,8 @@ This will be shown in the plugin info commands.
 
 The version of the Paper API that your plugin is using. This doesn't include the minor version until 1.20.5. From 1.20.5 and onward, a minor version is supported.
 Servers with a version lower than the version specified here will refuse to load the plugin.
-The valid versions are 1.13 - <SoftwareVersion versionType={"maj-min-pat"}/>.
-- <VersionFormattedCode>`api-version: '%%_MAJ_MIN_PAT_MC_%%'`</VersionFormattedCode>
+The valid versions are 1.13 - {LATEST_PAPER_RELEASE}.
+- <code>api-version: '${LATEST_PAPER_RELEASE}'</code>
 
 :::note
 
@@ -132,15 +131,15 @@ libraries:
 
 This is a list of permissions that your plugin uses. This is useful for plugins that use permissions to restrict access to certain features.
 ```yaml
-permissions :
-    permission.node:
-        description: "This is a permission node"
-        default: op
-        children:
-            permission.node.child: true
-    another.permission.node:
-        description: "This is another permission node"
-        default: not op
+permissions:
+  permission.node:
+    description: "This is a permission node"
+    default: op
+    children:
+      permission.node.child: true
+  another.permission.node:
+    description: "This is another permission node"
+    default: not op
 ```
 
 The description is the description of the permission node. This is what will be displayed in the permissions list.
@@ -158,12 +157,12 @@ The default value that permissions that don't have a `default` specified will ha
 This is a list of commands that your plugin uses. This is useful for plugins that use commands to provide features.
 ```yaml
 commands:
-    command:
-        description: "This is a command"
-        usage: "/command <arg>"
-        aliases: [cmd, command]
-        permission: permission.node
-        permission-message: "You do not have permission to use this command"
+  command:
+    description: "This is a command"
+    usage: "/command <arg>"
+    aliases: [cmd, command]
+    permission: permission.node
+    permission-message: "You do not have permission to use this command"
 ```
 
 - `description` is the description of the command. This gives a brief description of what the command does.
@@ -181,10 +180,10 @@ Be careful as these can cause plugin load issues if cyclical dependencies appear
 
 ```mermaid
 graph LR;
-    PluginA-->PluginB;
-    PluginB-->PluginC;
-    PluginC-->PluginD;
-    PluginD-->PluginA;
+  PluginA-->PluginB;
+  PluginB-->PluginC;
+  PluginC-->PluginD;
+  PluginD-->PluginA;
 ```
 
 Where `PluginA` and `PluginB` are plugins that depend on each other.
@@ -220,5 +219,5 @@ This is useful if you want to load your plugin before another plugin for the oth
 
 This can be used to tell the server that this plugin will provide the functionality of some library or other plugin (like an alias system).
 Plugins that (soft)depend on the other plugin will treat your plugin as if the other plugin exists when resolving dependencies or using
-<Javadoc name={"org.bukkit.plugin.PluginManager#getPlugin(java.lang.String)"}>`PluginManager#getPlugin(String)`</Javadoc>.
+[`PluginManager#getPlugin(String)`](jd:paper:org.bukkit.plugin.PluginManager#getPlugin(java.lang.String)).
 - `provides: [SomeOtherPlugin]`