fix: more broken URLs, verify Javadoc links (#598)

* feat: external URL improvements

* feat: use legacy bugs site for point to comment jira ticket

* fix: format astro.config.ts

* feat: remove lint dependency

* revert: test broken jd

* feat: rework jd markdown checks

* fix: jd to incorrect class

* fix: jd to incorrect package

* revert: another test

* chore: add user agent, change error message

---------

Co-authored-by: Matouš Kučera <[email protected]>

Author: Doc94

package.json

@@ -32,6 +32,7 @@
   "devDependencies": {
     "@types/mdast": "^4.0.4",
     "@types/node": "^22.15.16",
+    "dead-or-alive": "^1.0.4",
     "prettier": "3.5.3",
     "prettier-plugin-astro": "0.14.1",
     "prettier-plugin-organize-imports": "^4.1.0",

pnpm-lock.yaml

@@ -14,12 +14,12 @@ Reach out for support, or contact us on our forums.
 
 - [Forums](https://forums.papermc.io)
 
-## Twitter
+## Twitter/X
 
 We often tweet out version release notes, update notices, and other information via our Twitter
 page.
 
-- [@PaperPowered](https://twitter.com/PaperPowered)
+- [@PaperPowered](https://x.com/PaperPowered)
 
 You should not DM or @ this account for support. It is not checked as regularly as the above
 locations.

src/content/docs/misc/contact.md

@@ -33,7 +33,7 @@ representations in the legacy string format.
 Representing text as components is now the supported way of representing text for Paper and Velocity. They are used
 for almost all aspects of text being displayed to clients. Text like item names, lore, bossbars, team prefixes and
 suffixes, custom names, and much more all support components in respective APIs.
-[Mojang has stated](https://bugs.mojang.com/browse/MC-190605?focusedId=993040&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-993040)
+[Mojang has stated](https://bugs-legacy.mojang.com/browse/MC-190605?focusedId=993040&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-993040)
 that client support for the legacy format with `§` will be removed in the future.
 
 

src/content/docs/paper/dev/api/component-api/intro.md

@@ -156,9 +156,9 @@ public class UUIDDataType implements PersistentDataType<byte[], UUID> {
 :::note
 
 In order to use your own `PersistentDataType`, you must pass an instance of it to the
-[`get`](jd:paper:org.bukkit.persistence.PersistentDataContainer#get(org.bukkit.NamespacedKey,org.bukkit.persistence.PersistentDataType))/
+[`get`](jd:paper:io.papermc.paper.persistence.PersistentDataContainerView#get(org.bukkit.NamespacedKey,org.bukkit.persistence.PersistentDataType))/
 [`set`](jd:paper:org.bukkit.persistence.PersistentDataContainer#set(org.bukkit.NamespacedKey,org.bukkit.persistence.PersistentDataType,C))/
-[`has`](jd:paper:org.bukkit.persistence.PersistentDataContainer#has(org.bukkit.NamespacedKey,org.bukkit.persistence.PersistentDataType)) methods.
+[`has`](jd:paper:io.papermc.paper.persistence.PersistentDataContainerView#has(org.bukkit.NamespacedKey,org.bukkit.persistence.PersistentDataType)) methods.
 ```java
 container.set(key, new UUIDDataType(), uuid);
 ```

src/content/docs/paper/dev/api/pdc.md

@@ -119,7 +119,7 @@ dependencies {
 
 :::caution
 
-The Hikari library is not bundled with Paper, so you will need to shade/relocate it. In Gradle, you will need to use the [Shadow plugin](https://imperceptiblethoughts.com/shadow/).
+The Hikari library is not bundled with Paper, so you will need to shade/relocate it. In Gradle, you will need to use the [Shadow plugin](https://gradleup.com/shadow/).
 Alternatively, you can use the library loader with your Paper plugin to load the library at runtime. See [here](/paper/dev/getting-started/paper-plugins#loaders)
 for more information on how to use this.
 

src/content/docs/paper/dev/misc/databases.md

@@ -15,7 +15,7 @@ Velocity uses a number of open-source libraries:
 | [adventure](https://github.com/KyoriPowered/adventure)                          | [KyoriPowered](https://github.com/KyoriPowered)                          | [MIT License](https://github.com/KyoriPowered/adventure/blob/main/4/license.txt)                             |
 | [Brigadier](https://github.com/Mojang/brigadier)                                | [Mojang](https://www.minecraft.net)                                      | [MIT License](https://github.com/Mojang/brigadier/blob/master/LICENSE)                                       |
 | [event](https://github.com/KyoriPowered/event)                                  | [KyoriPowered](https://github.com/KyoriPowered)                          | [MIT License](https://github.com/KyoriPowered/event/blob/master/license.txt)                                 |
-| [ASM](http://asm.ow2.org/)                                                      | [OW2](https://www.ow2.org/)                                              | [BSD 3-Clause License](http://asm.ow2.io/license.html)                                                       |
+| [ASM](https://asm.ow2.io/)                                                      | [OW2](https://asm.ow2.io/)                                               | [BSD 3-Clause License](https://asm.ow2.io/license.html)                                                      |
 | [SLF4J](https://github.com/qos-ch/slf4j)                                        | [SLF4J](https://www.slf4j.org/)                                          | [MIT License](https://github.com/qos-ch/slf4j/blob/master/LICENSE.txt)                                       |
 | [Log4j](https://logging.apache.org/log4j/2.x/)                                  | [Log4j Team](https://logging.apache.org/log4j/2.3.x/log4j-web/team-list) | [Apache License 2.0](https://logging.apache.org/log4j/2.12.x/license.html)                                   |
 | [TerminalConsoleAppender](https://github.com/Minecrell/TerminalConsoleAppender) | [Minecrell](https://github.com/Minecrell)                                | [MIT License](https://github.com/Minecrell/TerminalConsoleAppender/blob/master/LICENSE)                      |
@@ -24,7 +24,7 @@ Velocity uses a number of open-source libraries:
 | [HOCON](https://github.com/lightbend/config)                                    | [lightbend](https://github.com/lightbend)                                | [Apache License 2.0](https://github.com/lightbend/config/blob/master/LICENSE-2.0.txt)                        |
 | [toml4j](https://github.com/mwanji/toml4j)                                      | [Moandji Ezana](https://github.com/mwanji)                               | [MIT License](https://github.com/mwanji/toml4j/blob/master/LICENSE)                                          |
 | [Night-Config](https://github.com/TheElectronWill/night-config)                 | [TheElectronWill](https://github.com/TheElectronWill)                    | [GNU Lesser General Public License 3.0](https://github.com/TheElectronWill/night-config/blob/master/LICENSE) |
-| [fastutil](http://fastutil.di.unimi.it/)                                        | [Sebastiano Vigna](http://vigna.di.unimi.it/)                            | [Apache License 2.0](https://github.com/vigna/fastutil/blob/master/LICENSE-2.0)                              |
+| [fastutil](https://fastutil.di.unimi.it/)                                       | [Sebastiano Vigna](https://vigna.di.unimi.it/)                           | [Apache License 2.0](https://github.com/vigna/fastutil/blob/master/LICENSE-2.0)                              |
 | [JLine](https://github.com/jline/jline3/blob/master/LICENSE.txt)                | [JLine project](https://github.com/jline/jline3)                         | [BSD 3-Clause License](https://github.com/jline/jline3/blob/master/LICENSE.txt)                              |
 | [AsyncHttpClient](https://github.com/AsyncHttpClient/async-http-client)         | [Stephane Landelle](https://github.com/slandelle)                        | [Apache License 2.0](https://github.com/AsyncHttpClient/async-http-client/blob/master/LICENSE.txt)           |
 | [completable-futures](https://github.com/spotify/completable-futures)           | [Spotify](https://github.com/spotify)                                    | [Apache License 2.0](https://github.com/spotify/completable-futures/blob/master/LICENSE)                     |

src/content/docs/velocity/admin/reference/libraries.md

@@ -219,7 +219,7 @@ You'll notice that your events don't need to extend or implement anything. They
 
 To fire the event, you'll need to get the server's event manager and use the
 [`fire`](jd:velocity:com.velocitypowered.api.event.EventManager#fire(E))
-method. Note that this returns a [`CompletableFuture`](jd:velocity:java.util.concurrent.CompletableFuture),
+method. Note that this returns a [`CompletableFuture`](jd:java:java.util.concurrent.CompletableFuture),
 so if you want to continue logic after the event is handled by all listeners, use a callback:
 
 ```java

src/content/docs/velocity/dev/api/event.md

@@ -1,4 +1,5 @@
 import type { RemarkPlugin } from "@astrojs/markdown-remark";
+import { deadOrAlive } from "dead-or-alive";
 import { visit } from "unist-util-visit";
 
 // replaces special Markdown links with Javadoc URLs
@@ -20,7 +21,7 @@ const asUrl = (name: string): string => {
   return `${name0}.html` + (hash ? `#${hash}` : "");
 };
 
-const parse = (url: string, { targets }: Options): string | null => {
+const parse = async (url: string, { targets }: Options): Promise<string | null> => {
   const match = /^jd:(.+?)(?::(.+?))?(?::(.+?))?$/.exec(url);
   if (!match) {
     return null;
@@ -40,14 +41,31 @@ const parse = (url: string, { targets }: Options): string | null => {
 
   const module = match[3] ? match[2] : typeof target !== "string" ? target.module : undefined;
 
-  return `${targetUrl}/${module ? `${module}/` : ""}${asUrl(name)}`;
+  const parsed: string = `${targetUrl}/${module ? `${module}/` : ""}${asUrl(name)}`;
+
+  const result = await deadOrAlive(parsed, {
+    findUrls: false,
+    followMetaHttpEquiv: false,
+    userAgent: "PaperMC/docs (https://docs.papermc.io)",
+  });
+  if (result.status !== "alive") {
+    throw new Error(`Javadoc link "${url}" is not valid`);
+  }
+
+  return parsed;
 };
 
 const plugin: RemarkPlugin = (options: Options) => {
-  return (tree) => {
+  return async (tree) => {
+    const promises: Promise<void>[] = [];
     visit(tree, "link", (node) => {
-      node.url = parse(node.url, options) ?? node.url;
+      promises.push(
+        parse(node.url, options).then((url) => {
+          node.url = url ?? node.url;
+        })
+      );
     });
+    await Promise.all(promises);
   };
 };