feat: finish internal and tips part, fix all broken links

Author: MC-XiaoHei

docs/.vitepress/config.mts

@@ -34,7 +34,6 @@ const vitepressOptions: UserConfig = {
     description: "Website of CommandAPI",
     cleanUrls: true,
     metaChunk: true,
-    ignoreDeadLinks: true, // TODO remove when all things are done
     rewrites: {
         'en/:rest*': ':rest*'
     },

docs/.vitepress/theme/style/global.css

@@ -25,5 +25,7 @@
 }
 
 .mermaid {
-    display:flex; justify-content:center;align-items:center
+    display: flex;
+    justify-content: center;
+    align-items: center;
 }

docs/en/create-commands/arguments/suggestions/suggestions.md

@@ -26,7 +26,7 @@ Because argument suggestions are arguably the most powerful feature that the Com
 
 ## The `ArgumentSuggestions` interface
 
-The two methods above require an `ArgumentSuggestions` object, which is a functional interface that takes in a `SuggestionInfo` record and the current Brigadier `SuggestionsBuilder` and returns a `CompletableFuture<Suggestions>` object. This may sound a bit complicated, but this allows you to implement very powerful suggestions using a combination of the CommandAPI and raw Brigadier API methods. More information about using Brigadier-level suggestions can be found in the [brigadier suggestions](./brigadiersuggestions.md) section.
+The two methods above require an `ArgumentSuggestions` object, which is a functional interface that takes in a `SuggestionInfo` record and the current Brigadier `SuggestionsBuilder` and returns a `CompletableFuture<Suggestions>` object. This may sound a bit complicated, but this allows you to implement very powerful suggestions using a combination of the CommandAPI and raw Brigadier API methods. More information about using Brigadier-level suggestions can be found in the [brigadier suggestions](../../../internal/brigadier-suggestions) section.
 
 To simplify this, the CommandAPI provides a number of methods to generate suggestions:
 

docs/en/create-commands/requirements.md

@@ -103,7 +103,7 @@ So now we've added the ability to create a party if we're not already in it. Now
 <<< @/../reference-code/src/main/kotlin/createcommands/Requirements.kt#partySystemExampleStep4
 :::
 
-Notice something here? There's some code repetition for the `withRequirement` method - this is the same predicate that we used earlier, except we remove the negation. If you are interested, you can view the section [Predicate tips](./predicatetips.md) for a method to improve code reuse.
+Notice something here? There's some code repetition for the `withRequirement` method - this is the same predicate that we used earlier, except we remove the negation. If you are interested, you can view the section [Predicate tips](../tips/predicate-tips) for a method to improve code reuse.
 
 Once the arguments have been declared, we can now implement our party teleportation command:
 

docs/en/internal/brigadier-plus-commandapi.md

@@ -0,0 +1,156 @@
+---
+order: 2
+authors:
+  - JorelAli
+  - willkroboth
+  - DerEchtePilz
+---
+
+# Brigadier + CommandAPI
+
+So far, we've been using only the CommandAPI to register commands. As a result, this makes the CommandAPI's features limited by whatever the CommandAPI has implemented. To push past these limits, the CommandAPI includes some extra methods to help with invoking brigadier methods. Of course, to use these methods, brigadier is required. The brigadier dependency's installation instructions can be found [here](https://github.com/Mojang/brigadier#installation).
+
+> **Developer's Note:**
+>
+> For those that are unaware, [brigadier](https://github.com/Mojang/brigadier) is Mojang's command parser and dispatching framework. This is what the CommandAPI wraps around and is the main underlying source of its functionality.
+
+The CommandAPI has been designed in such a way that you shouldn't have to access NMS in order to make use of the more "advanced" arguments and features - if you find that NMS is required to do something, [please make a new issue](https://github.com/CommandAPI/CommandAPI/issues/new/choose)!
+
+## Brigadier support functions
+
+The CommandAPI offers the following methods in the `dev.jorel.commandapi.Brigadier` class:
+
+```java
+public static CommandDispatcher getCommandDispatcher();
+public static RootCommandNode getRootNode();
+public static LiteralArgumentBuilder fromLiteralArgument(LiteralArgument literalArgument);
+public static RedirectModifier fromPredicate(BiPredicate<CommandSender, Object[]> predicate, List<Argument> args);
+public static Command fromCommand(CommandAPICommand command);
+public static RequiredArgumentBuilder fromArgument(List<Argument> args, Argument<?> argument);
+public static RequiredArgumentBuilder fromArgument(Argument argument);
+public static SuggestionProvider toSuggestions(Argument<?> argument, List<Argument> args);
+public static Object[] parseArguments(CommandContext cmdCtx, List<Argument> args);
+public static Object getBrigadierSourceFromCommandSender(CommandSender sender);
+public static CommandSender getBukkitCommandSenderFromContext(CommandContext cmdCtx);
+```
+
+Briefly, here's what each of these functions do (you can view the JavaDocs for more information):
+
+| Method                                | Description                                                                                                                                |
+|---------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------|
+| `getCommandDispatcher`                | Returns the Minecraft command dispatcher graph                                                                                             |
+| `getRootNode`                         | Returns the root node of the command dispatcher.<br>This is equivalent to using<br />`getCommandDispatcher().getRoot();`                   |
+| `fromLiteralArgument`                 | Creates a `LiteralArgumentBuilder` from a `LiteralArgument`                                                                                |
+| `fromPredicate`                       | Converts a predicate and some arguments into a `RedirectModifier`. This can be used for the `fork` method in brigadier's `ArgumentBuilder` |
+| `fromCommand`                         | Converts a `CommandAPICommand` into a brigadier `Command` object                                                                           |
+| `fromArgument`                        | Converts an argument, or a list of arguments, into a `RequiredArgumentBuilder`                                                             |
+| `toSuggestions`                       | Converts an argument's suggestions into brigadier's `SuggestionProvider`, with a list of previously declared arguments                     |
+| `parseArguments`                      | Parses a list of CommandAPI arguments into their respective objects for a provided `CommandContext`                                        |
+| `getBrigadierSourceFromCommandSender` | Converts a Bukkit `CommandSender` into the NMS command sender source object                                                                |
+| `getBukkitCommandSenderFromContext`   | Converts a Brigadier `CommandContext` into a Bukkit `CommandSender`                                                                        |
+
+## Examples
+
+I hope these examples help understand how the CommandAPI can help with registering more "powerful" commands with the use of brigadier as well! Please bear with with it - these examples can be long, but I'm certain that they've been explained well and will be useful!
+
+::::tip Example - Adding a predicate to the 'execute' command
+
+Say we wanted to add a predicate to the `/execute` command. In this example, we'll create a predicate which handles random chances. To illustrate this, we want to be able to run commands such as:
+
+```mccmd
+/execute if randomchance 1 4 run say Hello!
+```
+
+In this scenario, if we ran this command, we would expect "Hello!" to appear in the chat with a $\frac{1}{4}$ chance. In particular, this is what we're trying to achieve:
+
+- We want to create a predicate (true/false value) for the following syntax:
+
+  ```mccmd
+  randomchance <numerator> <denominator>
+  ```
+
+- We also want this predicate to come _after_ `execute if`:
+
+```mermaid
+graph TD
+    A(execute) --> B(if)
+    B --> C("randomchance&nbsp;&lt;numerator&gt;&nbsp;&lt;denominator&gt;")
+```
+
+- After entering our predicate, we want to route back to `execute` (because the argument after `execute` is `run`, which is used in our example command above):
+
+```mermaid
+graph TD
+    A(execute) --> B(if)
+    B --> C("randomchance&nbsp;&lt;numerator&gt;&nbsp;&lt;denominator&gt;")
+    C --> D(execute)
+```
+
+#### Writing the code
+
+Now that we've established what we want, we can finally begin writing the code! First we want to create a literal `randomchance`. It's a literal because literal values don't change (similar to say `run` or `if` from the `/execute` command). To create a literal, we'll use the `fromLiteralArgument` method described above, and then build it using the `.build()` method:
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/internal/BrigadierPlusCommandAPI.java#addPredicateExampleStep1
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/internal/BrigadierPlusCommandAPI.kt#addPredicateExampleStep1
+:::
+
+With that completed, we can now create our "argument" to this predicate. To do this, we'll use the regular declaration of arguments that we would normally use for commands. In this example, because we're computing $\frac{numerator}{denominator}$, we want our numerator to be 0 or greater and our denominator to be 1 or greater (we don't want any negative numbers or division by zero!):
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/internal/BrigadierPlusCommandAPI.java#addPredicateExampleStep2
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/internal/BrigadierPlusCommandAPI.kt#addPredicateExampleStep2
+:::
+
+Now we're going to get into the very nitty-gritty part - the predicate declaration. First, we'll create some variables `numerator` and `denominator` to represent the brigadier instances of these arguments. This can be handled by using the `Brigadier.argBuildOf` function:
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/internal/BrigadierPlusCommandAPI.java#addPredicateExampleStep3
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/internal/BrigadierPlusCommandAPI.kt#addPredicateExampleStep3
+:::
+
+Now we'll define our predicate. Since this is sort of a "meta-command" (it directly affects the outcome of the `run` command), we need to use the `ArgumentBuilder`'s `fork` method. Remember that after we run this predicate, we want to link back to `execute` again, so our first argument is the `CommandNode` for `execute`, which we can get using `Brigadier.getRootNode().getChild("execute")`. Then, we can simply use `Brigadier.fromPredicate` to finish our declaration:
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/internal/BrigadierPlusCommandAPI.java#addPredicateExampleStep4
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/internal/BrigadierPlusCommandAPI.kt#addPredicateExampleStep4
+:::
+
+Finally, we can now link everything up. We know that `numerator` comes first, **then** `denominator`, so we have to have `numerator.then(denominator)`. We also know that these arguments are the **children** of the `randomChance` literal, so we use the following code to state all of this:
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/internal/BrigadierPlusCommandAPI.java#addPredicateExampleStep5
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/internal/BrigadierPlusCommandAPI.kt#addPredicateExampleStep5
+:::
+
+Finally, we "register" the command. In this case, we're actually just adding the `randomChance` node under `execute → if`, which we can add using the following code:
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/internal/BrigadierPlusCommandAPI.java#addPredicateExampleStep6
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/internal/BrigadierPlusCommandAPI.kt#addPredicateExampleStep6
+:::
+
+#### Code summary
+
+So, hopefully that wasn't too confusing! If you're still lost, here's the whole code that we wrote:
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/internal/BrigadierPlusCommandAPI.java#addPredicateExample
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/internal/BrigadierPlusCommandAPI.kt#addPredicateExample
+:::
+
+::::

docs/en/internal/brigadier-suggestions.md

@@ -0,0 +1,100 @@
+---
+order: 3
+authors:
+  - JorelAli
+  - willkroboth
+  - DerEchtePilz
+---
+
+# Brigadier Suggestions
+
+As described in [The ArgumentSuggestions interface](../create-commands/arguments/suggestions/suggestions#the-argumentsuggestions-interface), the `ArgumentSuggestions` interface has the following default method:
+
+```java
+@FunctionalInterface
+public interface ArgumentSuggestions<CommandSender> {
+    
+    /**
+     * Create a {@link CompletableFuture} resolving onto a brigadier {@link Suggestions} object.
+     * @param info The suggestions info
+     * @param builder The Brigadier {@link SuggestionsBuilder} object
+     * @return a {@link CompletableFuture} resolving onto a brigadier {@link Suggestions} object.
+     *
+     * @throws CommandSyntaxException if there is an error making suggestions
+     */
+    CompletableFuture<Suggestions> suggest(SuggestionInfo<CommandSender> info, SuggestionsBuilder builder)
+        throws CommandSyntaxException;
+    
+}
+```
+
+This allows you to use Brigadier's `SuggestionsBuilder` and `Suggestions` classes to create more powerful suggestions beyond the basic capabilities of the CommandAPI.
+
+In order to use this, you will need the Brigadier dependency, which you can find under the [Brigadier installation instructions](https://github.com/Mojang/brigadier#installation).
+
+::::tip Example - Making an emoji broadcasting message
+
+Say we want to let users broadcast a message, but also allow them to enter emojis into the message they're typing:
+
+![A gif showcasing a command where emojis are suggested when typing a message](/images/emojimsg.gif)
+
+For this command, we'll use a `GreedyStringArgument` as if we were making a generic broadcasted message. We create a map of emojis to their descriptions to use as tooltips and then we use Brigadier to display the suggestions at the end of the message where the cursor is.
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/internal/BrigadierSuggestions.java#emojiCommandExample
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/internal/BrigadierSuggestions.kt#emojiCommandExample
+:::
+
+In this example, we simply create the `GreedyStringArgument` and use `replaceSuggestions()` to specify our suggestion rules. We create an offset using the current builder to make suggestions start at the last character (the current builder start `builder.getStart()` and the current length of what the user has already typed `info.currentArg().length()`). Finally, we build the suggestions with `builder.buildFuture()` and then register our command as normal.
+
+::::
+
+::::tip Example - Using a Minecraft command as an argument
+
+:::info
+
+This example has been superseded by the [Command argument](../create-commands/arguments/types/command-arguments). This example is still present as it gives an example of much more complicated brigadier suggestions which may be useful for readers!
+
+:::
+
+Courtesy of [469512345](https://github.com/469512345), the following example shows how using Brigadier's suggestions and parser can be combined with the CommandAPI to create an argument which suggests valid Minecraft commands. This could be used for example as a `sudo` command, to run a command as another player.
+
+![A gif showcasing a command suggestion for the /give command](/images/commandargument.gif)
+
+For this command, we'll use a `GreedyStringArgument` because that allows users to enter any combination of characters (which therefore, allows users to enter any command). First, we start by defining the suggestions that we'll use for the `GreedyStringArgument`. We'll use the `ArgumentSuggestions` functional interface described above:
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/internal/BrigadierSuggestions.java#commandArgumentsExampleStep1
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/internal/BrigadierSuggestions.kt#commandArgumentsExampleStep1
+:::
+
+There's a lot to unpack there, but it's generally split up into 4 key sections:
+
+- **Finding the start of the argument**. We find the start of the argument so we know where the beginning of our command suggestion is. This is done easily using `builder.getStart()`, but we also have to take into account any spaces if our command argument contains spaces.
+
+- **Parsing the command argument**. We make use of Brigadier's `parse()` method to parse the argument and generate some `ParseResults`.
+
+- **Reporting parsing errors**. This is actually an optional step, but in general it's good practice to handle exceptions stored in `ParseResults`. While [Brigadier doesn't actually handle suggestion exceptions](https://github.com/Mojang/brigadier/blob/master/src/main/java/com/mojang/brigadier/CommandDispatcher.java#L599), this has been included in this example to showcase exception handling.
+
+- **Generating suggestions from parse results**. We use our parse results with Brigadier's `getCompletionSuggestions()` method to generate some suggestions based on the parse results and the suggestion string range.
+
+Now that we've declared our arguments suggestions, we can then create our simple command with the following syntax:
+
+```mccmd
+/commandargument <command>
+```
+
+We use the command suggestions declared above by using the `replaceSuggestions` method in our `GreedyStringArgument`, and write a simple executor which runs the command that the user provided:
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/internal/BrigadierSuggestions.java#commandArgumentsExampleStep2
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/internal/BrigadierSuggestions.kt#commandArgumentsExampleStep2
+:::
+
+::::