diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 17e03033..4290c208 100644 --- a/CONTRIBUTING.md +++ b/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 + +``` + +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 diff --git a/config-specs/properties.json b/config-specs/properties.json new file mode 100644 index 00000000..8b1baf58 --- /dev/null +++ b/config-specs/properties.json @@ -0,0 +1,5 @@ +{ + "PAPER_JAVA_MIN": "17", + "PAPER_JAVA_RECOMMENDED": "21", + "VELOCITY_JAVA_MIN": "17" +} diff --git a/docs/paper/admin/getting-started/getting-started.md b/docs/paper/admin/getting-started/getting-started.mdx similarity index 75% rename from docs/paper/admin/getting-started/getting-started.md rename to docs/paper/admin/getting-started/getting-started.mdx index 9a6d290a..3a018cea 100644 --- a/docs/paper/admin/getting-started/getting-started.md +++ b/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 ** to run. We recommend using +**Java **, 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 | ## Downloading Paper diff --git a/docs/velocity/README.mdx b/docs/velocity/README.mdx index 099a162c..3ee0cb43 100644 --- a/docs/velocity/README.mdx +++ b/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 diff --git a/docs/velocity/admin/getting-started/README.md b/docs/velocity/admin/getting-started/README.mdx similarity index 97% rename from docs/velocity/admin/getting-started/README.md rename to docs/velocity/admin/getting-started/README.mdx index a76737aa..10a2f776 100644 --- a/docs/velocity/admin/getting-started/README.md +++ b/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 or newer. See our +[Java installation guide](/misc/java-install) for detailed instructions. ## Downloading Velocity diff --git a/docs/velocity/admin/getting-started/faq.md b/docs/velocity/admin/getting-started/faq.mdx similarity index 98% rename from docs/velocity/admin/getting-started/faq.md rename to docs/velocity/admin/getting-started/faq.mdx index 671ae81f..8e8c1e5a 100644 --- a/docs/velocity/admin/getting-started/faq.md +++ b/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 or above. ## Where can I find Velocity plugins? diff --git a/docs/velocity/dev/getting-started/creating-your-first-plugin.mdx b/docs/velocity/dev/getting-started/creating-your-first-plugin.mdx index 6efe2506..1dd91efc 100644 --- a/docs/velocity/dev/getting-started/creating-your-first-plugin.mdx +++ b/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 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.` or if you don't have GitHub you can just use `me.`. | | **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 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: diff --git a/docs/velocity/dev/how-to/porting-from-velocity-1.md b/docs/velocity/dev/how-to/porting-from-velocity-1.mdx similarity index 95% rename from docs/velocity/dev/how-to/porting-from-velocity-1.md rename to docs/velocity/dev/how-to/porting-from-velocity-1.mdx index 9abf75c1..76efbb26 100644 --- a/docs/velocity/dev/how-to/porting-from-velocity-1.md +++ b/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 and above. ## Removal of legacy dependencies diff --git a/src/components/Property.tsx b/src/components/Property.tsx new file mode 100644 index 00000000..c0658ad1 --- /dev/null +++ b/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 = "" }: PropertyProps) { + if (!hasProperty(name)) { + return defaultValue; + } + + return getProperty(name); +} diff --git a/src/theme/MDXComponents.tsx b/src/theme/MDXComponents.tsx index c36af1fa..07dd276f 100644 --- a/src/theme/MDXComponents.tsx +++ b/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, };