refactor: build system dependency references

Author: zlataovce

CONTRIBUTING.md

@@ -12,7 +12,8 @@ To ensure a smooth and collaborative contribution process, please follow the gui
 5. [Version tags](#version-tags)
 6. [Automatic constant replacement](#automatic-constant-replacement)
 7. [Linking to Javadocs](#linking-to-javadocs)
-8. [Code of Conduct](#code-of-conduct)
+8. [Referencing a build system dependency](#referencing-a-build-system-dependency)
+9. [Code of Conduct](#code-of-conduct)
 
 ## Introduction
 
@@ -181,6 +182,45 @@ For that, you can use the `jd:project_name[:module_name][:class_or_member_refere
 [java.sql's Connection](jd:java:java.sql:java.sql.Connection)
 ```
 
+## Referencing a build system dependency
+
+If you wish to reference a build system (i.e. Gradle or Maven) dependency, you can use the `Dependency` component.
+
+```mdxjs
+import { LATEST_ADVENTURE_API_RELEASE } from "/src/utils/versions";
+
+{/* uses the "default" template */}
+<Dependency group="net.kyori" name="adventure-api" version={LATEST_ADVENTURE_API_RELEASE} />
+```
+
+The `default` template is fit for use with a simple `implementation`/`compile`-scope dependency from Maven Central,
+however you can also make your own template.
+
+If you need to declare the dependency in a unique way and/or need to add other configuration in the build script, simply use
+the `Tabs` component with the corresponding code blocks - **do not make a template unless you plan to use it more than once**.
+
+```mdxjs
+import { Tabs, TabItem } from "@astrojs/starlight/components";
+
+<Tabs syncKey="build-system">
+  <TabItem label="Gradle (Kotlin)">
+    ```kotlin title="build.gradle.kts"
+    // my awesome build script in Kotlin
+    ```
+  </TabItem>
+  <TabItem label="Gradle (Groovy)">
+    ```groovy title="build.gradle"
+    // my awesome build script in Groovy
+    ```
+  </TabItem>
+  <TabItem label="Maven">
+    ```xml title="pom.xml"
+    <!-- my awesome build script in XML -->
+    ```
+  </TabItem>
+</Tabs>
+```
+
 ## Code of Conduct
 
 Contributors are expected to follow the [Community Guidelines](https://papermc.io/community/guidelines) of the PaperMC organization in all

astro.config.ts

@@ -4,14 +4,14 @@ import d2 from "astro-d2";
 import { defineConfig } from "astro/config";
 import starlightLinksValidator from "starlight-links-validator";
 import starlightSidebarTopics from "starlight-sidebar-topics";
-import miniMessageHighlight from "./src/assets/mm.tmLanguage.json";
 import codeConstantsPlugin from "./src/utils/remark/code_const";
 import javadocPlugin from "./src/utils/remark/javadoc";
+import miniMessageHighlight from "./src/utils/shiki/mm.tmLanguage.json";
 import {
-  LATEST_ADVENTURE_ANSI_RELEASE,
   LATEST_ADVENTURE_API_RELEASE,
   LATEST_ADVENTURE_PLATFORM_MOD_RELEASE,
   LATEST_ADVENTURE_PLATFORM_RELEASE,
+  LATEST_ANSI_RELEASE,
   LATEST_FOLIA_RELEASE,
   LATEST_MC_RELEASE,
   LATEST_PAPER_RELEASE,
@@ -553,7 +553,7 @@ export default defineConfig({
             LATEST_ADVENTURE_API_RELEASE,
             LATEST_ADVENTURE_PLATFORM_RELEASE,
             LATEST_ADVENTURE_PLATFORM_MOD_RELEASE,
-            LATEST_ADVENTURE_ANSI_RELEASE,
+            LATEST_ANSI_RELEASE,
           },
         },
       ],

src/components/Dependency.astro

@@ -0,0 +1,124 @@
+---
+import { Code, TabItem, Tabs } from "@astrojs/starlight/components";
+import { LATEST_ADVENTURE_PLATFORM_MOD_RELEASE } from "../utils/versions";
+
+type TemplateKey = "default" | "adventure-platform-mod";
+
+interface Template {
+  label: string;
+  lang?: string;
+  title?: string;
+  code: string;
+}
+
+const templates: Record<TemplateKey, Template[]> = {
+  default: [
+    {
+      label: "Gradle (Kotlin)",
+      lang: "kotlin",
+      title: "build.gradle.kts",
+      code: `repositories {
+  mavenCentral()
+}
+
+dependencies {
+  implementation("\{GROUP}:\{NAME}:\{VERSION}")
+}`,
+    },
+    {
+      label: "Gradle (Groovy)",
+      lang: "groovy",
+      title: "build.gradle",
+      code: `repositories {
+  mavenCentral()
+}
+
+dependencies {
+  implementation '\{GROUP}:\{NAME}:\{VERSION}'
+}`,
+    },
+    {
+      label: "Maven",
+      lang: "xml",
+      title: "pom.xml",
+      code: `<project>
+  <dependencies>
+    <dependency>
+      <groupId>\{GROUP}</groupId>
+      <artifactId>\{NAME}</artifactId>
+      <version>\{VERSION}</version>
+    </dependency>
+  </dependencies>
+</project>`,
+    },
+  ],
+  "adventure-platform-mod": [
+    {
+      label: "Gradle (Kotlin)",
+      lang: "kotlin",
+      title: "build.gradle.kts",
+      code: `repositories {
+  // for development builds
+  maven(url = "https://s01.oss.sonatype.org/content/repositories/snapshots/") {
+    name = "sonatype-oss-snapshots1"
+    mavenContent { snapshotsOnly() }
+  }
+  // for releases
+  mavenCentral()
+}
+
+dependencies {
+  modImplementation(include("net.kyori:adventure-platform-\{NAME}:${LATEST_ADVENTURE_PLATFORM_MOD_RELEASE}")!!) // for Minecraft 1.21.5
+}`,
+    },
+    {
+      label: "Gradle (Groovy)",
+      lang: "groovy",
+      title: "build.gradle",
+      code: `repositories {
+  // for development builds
+  maven {
+    name = 'sonatype-oss-snapshots1'
+    url = 'https://s01.oss.sonatype.org/content/repositories/snapshots/'
+    mavenContent { snapshotsOnly() }
+  }
+  // for releases
+  mavenCentral()
+}
+
+dependencies {
+  modImplementation include('net.kyori:adventure-platform-\{NAME}:${LATEST_ADVENTURE_PLATFORM_MOD_RELEASE}') // for Minecraft 1.21.5
+}`,
+    },
+  ],
+};
+
+interface Props {
+  group?: string;
+  name?: string;
+  version?: string;
+  template?: TemplateKey;
+}
+
+let { group = "", name = "", version = "", template } = Astro.props;
+template = template ?? "default";
+
+const templateData = templates[template];
+if (!templateData) {
+  throw new Error(`Template '${template}' not found`);
+}
+
+const formatCode = (code: string): string => {
+  return code.replaceAll("\{GROUP}", group).replaceAll("\{NAME}", name).replaceAll("\{VERSION}", version);
+};
+---
+
+<Tabs syncKey="build-system">
+  {
+    templateData.map(({ label, lang, title, code }) => (
+      <TabItem {label}>
+        <Code {lang} {title} code={formatCode(code)} />
+      </TabItem>
+    ))
+  }
+</Tabs>