Merge branch 'wiki' into feat/wiki-deluxemenus-placeholders

.github/workflows/publish_site.yml

@@ -57,7 +57,7 @@ jobs:
       - name: Build pages
         run: mkdocs build
       - name: Configure GitHub Pages
-        uses: actions/configure-pages@v4
+        uses: actions/configure-pages@v5
       - name: Upload Pages Artifact
         uses: actions/upload-pages-artifact@v3
         with:

README.md

@@ -87,7 +87,7 @@ $ git checkout -b <branch>
 
 It is now time to make your changes. It is recommended to use MkDocs and its live-preview feature to see your changes applied in real time whenever you save a file.
 
-To use the live-preview, run `mkdocs serve` in the same folder where the `mkdocs.yml` file is located. This should start a server on `http://127.0.0.1:8000` that you can open in your browser.  
+To use the live-preview, run `mkdocs serve` in the same folder where the `mkdocs.yml` file is located. This should start a server on `http://127.0.0.1:8000` that you can open in your browser. You can also append the `--open` argument to the command to make MkDocs open the preview directly, avoiding the need of having to open it yourself.  
 Should the command not work, check that you actually installed MkDocs and any required dependencies. The easiest way is to just execute `pip install mkdocs-material` to download the Material for MkDocs theme alongside additional dependencies, including MkDocs.
 
 To cancel the live preview, simply press <kbd>Ctrl</kbd>+<kbd>C</kbd> in the git-bash terminal to shut the live preview server down.
@@ -168,8 +168,9 @@ The following rules apply specifically to entries in the [Placeholder List][plac
     - Should an entry with the name already exist will you need to add yours after it.
 2.  An entry follows this specific format:
     ````markdown
-   - ### [<name>](<link>)
+    ### [<name>](<link>)
-       > <command>
+    /// <command>
+    ///
     
     <text>
     
@@ -180,7 +181,10 @@ The following rules apply specifically to entries in the [Placeholder List][plac
     - `<name>` is the name of the Placeholder expansion you add.
     - `<link>` is a link to the plugin this expansion is made for. If the expansion is not for a plugin should no link be added (Only `- ### <name>` be used).
         - Links to spigot pages need to be sanitized, meaning a link such as `https://www.spigotmc.org/resources/placeholderapi.6245/` becomes `https://www.spigotmc.org/resources/6245/`
-   - `<command>` is the [`/papi ecloud download`][download-command] used to get the expansion. Should the expansion not be on the eCloud will you need to put `NO DOWNLOAD COMMAND` here.
+    - `<command>` needs to be replaced with one of the following values, depending on how the expansion can be added:
+        - Should your expansion be built-in into a Plugin, add `integrated | Built into Plugin`
+        - Should your expansion be obtainable via the [`/papi ecloud download`][download-command] command, add `command | papi ecloud download <name of expansion>`
+        - Should your expansion only be downloadable via external sources (i.e. a GitHub Release), add `download | <link to download>`
     - `<text>` is an optional text that can be used to point to extra documentation. Please keep it short and simple.
     - `<placeholders>` would be all available placeholders. Each entry should be on a new line.
         - Please avoid explicit examples and instead use `<>` and `[]` to indicate required or optional values (i.e. instead of `%expansion_SomePlayer%` it would be `%expansion_<player>%`)

docs/assets/js/latest-release.js

@@ -10,10 +10,12 @@ document$.subscribe(async => {
     }
     
     async function fetchAPIInfo() {
-        const release = await fetch("https://papi-repo-proxy.vercel.app/repo/latest-release").then(_ => _.json());
+        const release = await fetch("https://repo.extendedclip.com/api/maven/latest/version/releases/me/clip/placeholderapi").then(_ => _.json());
+        
+        console.log(release)
         
         const data = {
-            "version": release.name
+            "version": release.version
         }
         
         __md_set("__api_tag", data, sessionStorage);

docs/assets/stylesheets/styling.css

@@ -1,3 +1,9 @@
+:root {
+    --md-admonition-icon--command: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16"><path d="M13.94 3.045a.75.75 0 0 0-1.38-.59l-4.5 10.5a.75.75 0 1 0 1.38.59l4.5-10.5ZM5 11.5a1.5 1.5 0 1 1-3 0 1.5 1.5 0 0 1 3 0Z"></path></svg>');
+    --md-admonition-icon--integrated: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16"><path d="M4 8H2.5a1 1 0 0 0-1 1v5.25a.75.75 0 0 1-1.5 0V9a2.5 2.5 0 0 1 2.5-2.5H4V5.133a1.75 1.75 0 0 1 1.533-1.737l2.831-.353.76-.913c.332-.4.825-.63 1.344-.63h.782c.966 0 1.75.784 1.75 1.75V4h2.25a.75.75 0 0 1 0 1.5H13v4h2.25a.75.75 0 0 1 0 1.5H13v.75a1.75 1.75 0 0 1-1.75 1.75h-.782c-.519 0-1.012-.23-1.344-.63l-.761-.912-2.83-.354A1.75 1.75 0 0 1 4 9.867Zm6.276-4.91-.95 1.14a.753.753 0 0 1-.483.265l-3.124.39a.25.25 0 0 0-.219.248v4.734c0 .126.094.233.219.249l3.124.39a.752.752 0 0 1 .483.264l.95 1.14a.25.25 0 0 0 .192.09h.782a.25.25 0 0 0 .25-.25v-8.5a.25.25 0 0 0-.25-.25h-.782a.25.25 0 0 0-.192.09Z"></path></svg>');
+    --md-admonition-icon--download: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16"><path d="M2.75 14A1.75 1.75 0 0 1 1 12.25v-2.5a.75.75 0 0 1 1.5 0v2.5c0 .138.112.25.25.25h10.5a.25.25 0 0 0 .25-.25v-2.5a.75.75 0 0 1 1.5 0v2.5A1.75 1.75 0 0 1 13.25 14Z"></path><path d="M7.25 7.689V2a.75.75 0 0 1 1.5 0v5.689l1.97-1.969a.749.749 0 1 1 1.06 1.06l-3.25 3.25a.749.749 0 0 1-1.06 0L4.22 6.78a.749.749 0 1 1 1.06-1.06l1.97 1.969Z"></path></svg>');
+}
+
 .md-header__button.md-logo img {
     height: 3rem;
 }
@@ -5,3 +11,55 @@
 .md-typeset .grid.cards.hide-list > ul > li > ul > li {
     list-style-type: none;
 }
+
+/***************************
+ * Custom Admonition boxes *
+ ***************************/
+
+/* Command */
+.md-typeset .admonition.command,
+.md-typeset details.command {
+  border-color: #00c853;
+}
+.md-typeset .command > .admonition-title,
+.md-typeset .command > summary {
+  background-color: #00c8531a;
+}
+.md-typeset .command > .admonition-title::before,
+.md-typeset .command > summary::before {
+  background-color: #00c853;
+  -webkit-mask-image: var(--md-admonition-icon--command);
+          mask-image: var(--md-admonition-icon--command);
+}
+
+/* Integrated (built-in) */
+.md-typeset .admonition.integrated,
+.md-typeset details.integrated {
+  border-color: #9e9e9e;
+}
+.md-typeset .integrated > .admonition-title,
+.md-typeset .integrated > summary {
+  background-color: #9e9e9e1a;
+}
+.md-typeset .integrated > .admonition-title::before,
+.md-typeset .integrated > summary::before {
+  background-color: #9e9e9e;
+  -webkit-mask-image: var(--md-admonition-icon--integrated);
+          mask-image: var(--md-admonition-icon--integrated);
+}
+
+/* Download */
+.md-typeset .admonition.download,
+.md-typeset details.download {
+    border-color: #00c853;
+}
+.md-typeset .download > .admonition-title,
+.md-typeset .download > summary {
+    background-color: #00c8531a;
+}
+.md-typeset .download > .admonition-title::before,
+.md-typeset .download > summary::before {
+    background-color: #00c853;
+  -webkit-mask-image: var(--md-admonition-icon--download);
+          mask-image: var(--md-admonition-icon--download);
+}

docs/developers/creating-a-placeholderexpansion.md

@@ -107,7 +107,7 @@ This method of creating a PlaceholderExpansion is recommended as it has the foll
 Internal PlaceholderExpansions are not automatically registered by PlaceholderAPI, due to them not being a separate jar file located in the expansion folder.  
 Please see the [Regsister your Expansion](#register-your-expansion) section for more details.
 
-You are also required to override and set `persistent()` to `true`. This tells PlaceholderAPI to not unload your expansion during plugin reload, as it would otherwise unregister your expansion, making it no longer work.
+You are also required to override and set `persist()` to `true`. This tells PlaceholderAPI to not unload your expansion during plugin reload, as it would otherwise unregister your expansion, making it no longer work.
 ///
 
 /// details | Full Example

docs/developers/using-placeholderapi.md

@@ -18,7 +18,7 @@ Use the below code example matching your dependency manager.
     <repositories>
         <repository>
             <id>placeholderapi</id>
-            <url>https://repo.extendedclip.com/content/repositories/placeholderapi/</url>
+            <url>https://repo.extendedclip.com/releases/</url>
         </repository>
     </repositories>
     <dependencies>
@@ -36,7 +36,7 @@ Use the below code example matching your dependency manager.
 ```{ .groovy title="build.gradle" data-md-component="api-version" }
 repositories {
     maven {
-        url = 'https://repo.extendedclip.com/content/repositories/placeholderapi/'
+        url = 'https://repo.extendedclip.com/releases/'
     }
 }
 
@@ -62,27 +62,39 @@ Next step is to go to your plugin.yml or paper-plugin.yml and add PlaceholderAPI
 /// tab | :simple-spigotmc: plugin.yml
 
 //// tab | Optional dependency
-```yaml
+
+///// note |
+Tab the :material-plus-circle: icons in the code block below for additional information.
+/////
+
+```{ .yaml .annotate title="plugin.yml" }
 name: ExamplePlugin
 version: 1.0
 author: author
 main: your.main.path.Here
 
-# This sets PlaceholderAPI as an optional dependency for your plugin.
+softdepend: ["PlaceholderAPI"] # (1)
-softdepend: [PlaceholderAPI]
 ```
+
+1.  This sets PlaceholderAPI as an optional dependency for your plugin.
 ////
 
 //// tab | Required dependency
-```yaml
+
+///// note |
+Tab the :material-plus-circle: icons in the code block below for additional information.
+/////
+
+```{ .yaml .annotate title="plugin.yml" }
 name: ExamplePlugin
 version: 1.0
 author: author
 main: your.main.path.Here
 
-# This sets PlaceholderAPI as a required dependency for your plugin.
+depend: ["PlaceholderAPI"] # (1)
-depend: [PlaceholderAPI]
 ```
+
+1.  This sets PlaceholderAPI as a required dependency for your plugin.
 ////
 
 ///
@@ -90,7 +102,12 @@ depend: [PlaceholderAPI]
 /// tab | :fontawesome-regular-paper-plane: paper-plugin.yml
 
 //// tab | Optional dependency
-```yaml
+
+///// note |
+Tab the :material-plus-circle: icons in the code block below for additional information.
+/////
+
+```{ .yaml .annotate title="paper-plugin.yml" }
 name: ExamplePlugin
 version: 1.0
 author: author
@@ -99,14 +116,21 @@ main: your.main.path.Here
 dependencies:
   server:
     PlaceholderAPI:
-      # Load order is relative to the dependency. So here PlaceholderAPI loads before our plugin.
+      load: BEFORE # (1) 
-      load: BEFORE
       required: false
 ```
+
+1.  Load order is relative to the Dependency.  
+    This means that in this example, PlaceholderAPI is loaded **before** your plugin.
 ////
 
 //// tab | Required dependency
-```yaml
+
+///// note |
+Tab the :material-plus-circle: icons in the code block below for additional information.
+/////
+
+```{ .yaml .annotate title="paper-plugin.yml" }
 name: ExamplePlugin
 version: 1.0
 author: author
@@ -115,10 +139,12 @@ main: your.main.path.Here
 dependencies:
   server:
     PlaceholderAPI:
-      # Load order is relative to the dependency. So here PlaceholderAPI loads before our plugin.
+      load: BEFORE # (1)
-      load: BEFORE
       required: true
 ```
+
+1.  Load order is relative to the Dependency.  
+    This means that in this example, PlaceholderAPI is loaded **before** your plugin.
 ////
 
 ///
@@ -134,10 +160,19 @@ To use placeholders from other plugins in our own plugin, we simply have to [(so
 
 It is also important to point out, that any required plugin/dependency for an expansion has to be on the server and enabled, or the `setPlaceholders` method will just return the placeholder itself (do nothing).
 
-/// example
+/// details | Example
+    type: example
+
 Let's assume we want to send a custom join message that shows the primary group a player has.  
 To achieve this, we can do the following:
-```java
+
+//// note |
+The below example assumes a **soft dependency** on PlaceholderAPI to handle PlaceholderAPI not being present more decently.
+
+Tab the :material-plus-circle: icons in the code block below for additional information.
+////
+
+```{ .java .annotate title="JoinExample.java" }
 package at.helpch.placeholderapi;
 
 import me.clip.placeholderapi.PlaceholderAPI;
@@ -155,18 +190,10 @@ public class JoinExample extends JavaPlugin implements Listener {
     @Override
     public void onEnable() {
  
-        if (Bukkit.getPluginManager().getPlugin("PlaceholderAPI") != null) {
+        if (Bukkit.getPluginManager().isPluginEnabled("PlaceholderAPI")) {
-            /*
+            Bukkit.getPluginManager().registerEvents(this, this); // (1)
-             * We register the EventListener here, when PlaceholderAPI is installed.
-             * Since all events are in the main class (this class), we simply use "this"
-             */
-            Bukkit.getPluginManager().registerEvents(this, this);
         } else {
-            /*
+            getLogger().warn("Could not find PlaceholderAPI! This plugin is required."); // (2)
-             * We inform about the fact that PlaceholderAPI isn't installed and then
-             * disable this plugin to prevent issues.
-             */
-            getLogger().warn("Could not find PlaceholderAPI! This plugin is required.");
             Bukkit.getPluginManager().disablePlugin(this);
         }
     }
@@ -175,16 +202,17 @@ public class JoinExample extends JavaPlugin implements Listener {
     public void onJoin(PlayerJoinEvent event) {
         String joinText = "%player_name% joined the server! They are rank %vault_rank%";
 
-        /*
+        joinText = PlaceholderAPI.setPlaceholders(event.getPlayer(), joinText); // (3)
-         * We parse the placeholders using "setPlaceholders"
-         * This would turn %vault_rank% into the name of the Group, that the
-         * joining player has, assuming Vault and the Vault expansion are
-         * on the server.
-         */
-        joinText = PlaceholderAPI.setPlaceholders(event.getPlayer(), joinText);
 
         event.setJoinMessage(joinText);
     }
 }
 ```
+
+1.  We check that PlaceholderAPI is present and enabled to then register events to handle (See below).
+2.  In case PlaceholderAPI is not present are we reporting this issue and disable the plugin.
+3.  Using `PlaceholderAPI.setPlaceholders(Player, String)` we can parse `%placeholder%` text in the provided String, should they have a matching expansion and said expansion return a non-null String.  
+    In our example are we providing a text containing `%player_name%` and `%vault_rank%` to be parsed, which require the Player and Vault expansion respectively.
+    
+    Example output: `Notch joined the server! They are rank Admin`
 ///

docs/users/plugins-using-placeholderapi.md

@@ -215,6 +215,9 @@ If your plugin isn't shown here and you want it to be added, [read the Wiki READ
 - **[CitizensBooks](https://www.spigotmc.org/resources/37465/)**
     - [x] Supports placeholders.
     - [ ] Provides own placeholders. [Link]
+- **[ClaimChunk](https://www.spigotmc.org/resources/44458/)**
+    - [x] Supports placeholders.
+    - [x] Provides own placeholders. [**[Link](placeholder-list.md#claimchunk)**]
 - **[Clans-API for Spigot/Clan tag in chat](https://www.spigotmc.org/resources/31547/)**
     - [ ] Supports placeholders.
     - [x] Provides own placeholders. [**[Link](placeholder-list.md#clans-api-for-spigotclan-tag-in-chat)**]

docs/users/using-placeholders.md

@@ -40,10 +40,11 @@ The way PlaceholderAPI's system works, allows a Placeholder Expansion and its co
 Depending on what type you have, will you need to do some extra steps to use the placeholder from the Placeholder Expansion.
 
 One way to find out, if an Expansion is included or separate, is to check the [Placeholder List](placeholder-list.md) page for any entry of it.  
-If it exists on the page, can you check, if the line right after the title says `NO DOWNLOAD COMMAND` or `/papi ecloud download ...` (i.e. `/papi ecloud download Player`).
+If it exists on the page, can you check the infobox right below the title of the Expansion for one of the following cases:
 
-If the line says the former, does it mean, the expansion is part of the plugin and doesn't need any extra steps to be active (Unless the plugin author mentions otherwise).  
+- `papi ecloud download <expansion>`: The expansion is on the ecloud and needs to be downloaded using the [`/papi ecloud download` command](commands.md#papi-ecloud-download).
-In the case of the later, will you need to download the expansion from the eCloud. Simply copy the command and execute it either in the console, or in-game. Afterwards, reload PlaceholderAPI using `/papi reload`.
+- `Built into Plugin`: The expansion is part of the plugin it depends on and doesn't require any steps to install, unless stated otherwise.
+- *A URL*: The Expansion needs to be downloaded from a separate source (i.e. a GitHub Release). You need to manually download and move the jar into the expansions folder.
 
 You can check what expansions are loaded by running `/papi list`.
 

mkdocs.yml

@@ -127,6 +127,9 @@ markdown_extensions:
         - bug
         - example
         - quote
+        - command
+        - integrated
+        - download
   - pymdownx.blocks.details
   - pymdownx.blocks.tab:
       alternate_style: true