feat: Property for documenting "magic" values consistently (#293)

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

CONTRIBUTING.md

@@ -142,6 +142,22 @@ for older versions. This is done by using yarn's docusaurus version command:
 yarn docusaurus docs:version:paper "1.20"
 ```
 
+## Magic Value Handling
+
+When writing documentation, it is important to avoid using "magic values" in the documentation. This may be slightly less
+obscure than in code, but it is still important to avoid using them. For example, these values may end up being used in
+multiple places, and if they change, it is important to change them in all places. This is why it is important to use
+our `Property` component to embed these values into the documentation. An example of this would be:
+
+```jsx
+<Property name="PAPER_JAVA_RECOMMENDED" />
+```
+
+This will embed the value of the property into the documentation, and if it changes, it will be changed in all places.
+
+These values are stored in the `config-specs/properties.json` file. If you need to add a new property, you can
+add it to this file, and it will be available to use in the documentation.
+
 ## Code of Conduct
 
 Contributors are expected to follow the [Community Guidelines](https://papermc.io/community/guidelines) of the PaperMC organization in all 

config-specs/properties.json

@@ -0,0 +1,5 @@
+{
+  "PAPER_JAVA_MIN": "17",
+  "PAPER_JAVA_RECOMMENDED": "21",
+  "VELOCITY_JAVA_MIN": "17"
+}

docs/paper/admin/getting-started/getting-started.md → docs/paper/admin/getting-started/getting-started.mdx

@@ -9,16 +9,17 @@ description: How to get started with downloading and setting up a Paper server.
 
 :::tip
 
-With the release of Minecraft 1.18, Paper now requires **Java 17** to run. We recommend using **Java 21**, which [is easy to download and install](/misc/java-install).
+Paper requires at least **Java <Property name="PAPER_JAVA_MIN" />** to run. We recommend using
+**Java <Property name="PAPER_JAVA_RECOMMENDED" />**, which [is easy to download and install](/misc/java-install).
 
 :::
 
-| Paper Version  | Recommended Java Version |
-|----------------|--------------------------|
-| 1.8 to 1.11    | Java 8                   |
-| 1.12 to 1.16.4 | Java 11                  |
-| 1.16.5         | Java 16                  |
-| 1.17.1-1.18.1+ | Java 21                  |
+| Paper Version  | Recommended Java Version                        |
+|----------------|-------------------------------------------------|
+| 1.8 to 1.11    | Java 8                                          |
+| 1.12 to 1.16.4 | Java 11                                         |
+| 1.16.5         | Java 16                                         |
+| 1.17.1-1.18.1+ | Java <Property name="PAPER_JAVA_RECOMMENDED" /> |
 
 ## Downloading Paper
 

docs/velocity/README.mdx

@@ -7,7 +7,7 @@ Velocity is the ridiculously scalable, flexible Minecraft proxy.
 ## Getting started
 
 It is simple to get started with Velocity. Get started with our
-[Getting Started guide](admin/getting-started/README.md).
+[Getting Started guide](admin/getting-started/README.mdx).
 
 ## I need help
 
@@ -19,7 +19,7 @@ We have put a lot of effort into documenting Velocity as much as possible with o
 our coverage will continue to expand. We strongly encourage you to check the sidebar of the docs for
 relevant resources. Helping yourself using the resources in these docs saves all of us time.
 
-We recommend you visit the [frequently-asked questions](admin/getting-started/faq.md) to begin your
+We recommend you visit the [frequently-asked questions](admin/getting-started/faq.mdx) to begin your
 search. Most common issues with Velocity are answered there.
 
 Please do not be offended if we respond to your question linking back here. Asking us a question

docs/velocity/admin/getting-started/README.md → docs/velocity/admin/getting-started/README.mdx

@@ -9,8 +9,8 @@ This page covers how to install and set up a minimal configuration of Velocity.
 ## Installing Java
 
 Velocity is written in Java, so if you do not already have Java installed, you will need to install
-it before you continue. Velocity requires Java 17 or newer. See our
-[java installation guide](/misc/java-install) for detailed instructions.
+it before you continue. Velocity requires Java <Property name="VELOCITY_JAVA_MIN" /> or newer. See our
+[Java installation guide](/misc/java-install) for detailed instructions.
 
 ## Downloading Velocity
 

docs/velocity/admin/getting-started/faq.md → docs/velocity/admin/getting-started/faq.mdx

@@ -10,7 +10,7 @@ many of these questions from the user perspective.
 
 ## What version of Java does Velocity require?
 
-Velocity 3.3.x requires Java 17 or above.
+Velocity 3.3.x requires Java <Property name="VELOCITY_JAVA_MIN" /> or above.
 
 ## Where can I find Velocity plugins?
 

docs/velocity/dev/getting-started/creating-your-first-plugin.mdx

@@ -26,7 +26,7 @@ IDEA is recommended.
 - Open your IDE
 - Click `Create New Project` or the equivalent
 - Select either `Gradle` or `Maven`
-- Make sure your **Project JDK** is Java 11 or later
+- Make sure your **Project JDK** is Java <Property name="VELOCITY_JAVA_MIN" /> or later
 - **Finish** the dialog and open the project.
 
 Now we have created our project, we need configure our build system.
@@ -174,7 +174,7 @@ You will be asked to provide some information about your project.
 | **Group ID**         | The group ID of your project. This is used for Maven and Gradle. This is usually your domain name in reverse. If you don't know what you should put here, you can use something like `io.github.<yourname>` or if you don't have GitHub you can just use `me.<yourname>`. |
 | **Artifact ID**      | The artifact ID of your project. This is used for Maven and Gradle. This is usually the name of your project. This is usually the same as the `Name` field.                                                                                                               |
 | **Version**          | The version of your project. This is used for Maven and Gradle. This is usually `1.0-SNAPSHOT` and does not really matter for now.                                                                                                                                        |
-| **JDK**              | The JDK you want to use. This can be anything from Java 11 and above.                                                                                                                                                                                                     |
+| **JDK**              | The JDK you want to use. This can be anything from Java <Property name="VELOCITY_JAVA_MIN" /> and above.                                                                                                                                                                  |
 
 Now you can click on the `Create` button and IntelliJ will create the project for you.
 If everything went well, you should see something like this:

docs/velocity/dev/how-to/porting-from-velocity-1.md → docs/velocity/dev/how-to/porting-from-velocity-1.mdx

@@ -10,7 +10,7 @@ document very carefully**.
 
 ## Minimum supported Java version bump
 
-Velocity 3.3.x now requires Java 17 and above.
+Velocity 3.3.x now requires Java <Property name="VELOCITY_JAVA_MIN" /> and above.
 
 ## Removal of legacy dependencies
 

src/components/Property.tsx

@@ -0,0 +1,22 @@
+import properties from "@site/config-specs/properties.json";
+
+export function hasProperty(key: string): boolean {
+  return key in properties;
+}
+
+export function getProperty(key: string): string | null {
+  return properties[key] ?? null;
+}
+
+interface PropertyProps {
+    name: string;
+    defaultValue?: string;
+}
+
+export default function Property({ name, defaultValue = "<placeholder>" }: PropertyProps) {
+  if (!hasProperty(name)) {
+    return defaultValue;
+  }
+
+  return getProperty(name);
+}

src/theme/MDXComponents.tsx

@@ -1,11 +1,12 @@
 import React from 'react';
 import { Icon } from '@iconify/react';
 import MDXComponents from '@theme-original/MDXComponents';
-import TabItem from "@theme/TabItem";
-import Tabs from "@theme/Tabs";
-import VersionFormattedCode from '../components/VersionFormattedCode';
-import SoftwareVersion from "../components/SoftwareVersion";
-import VersionedJavaDocLink from "../components/VersionedJavaDocLink";
+import TabItem from '@theme/TabItem';
+import Tabs from '@theme/Tabs';
+import VersionFormattedCode from '@site/src/components/VersionFormattedCode';
+import SoftwareVersion from '@site/src/components/SoftwareVersion';
+import VersionedJavaDocLink from '../components/VersionedJavaDocLink';
+import Property from '@site/src/components/Property';
 
 export default {
     // Re-use the default mapping
@@ -16,5 +17,6 @@ export default {
     VersionFormattedCode,
     SoftwareVersion,
     VersionedJavaDocLink,
+    Property,
     Icon: Icon,
 };