feat: version tag, redirects, fix codeblock line highlights

CONTRIBUTING.md

@@ -9,9 +9,10 @@ To ensure a smooth and collaborative contribution process, please follow the gui
 2. [How to add a page](#adding-a-page)
 3. [Submitting contributions](#submitting-contributions)
 4. [Style guidelines](#style-guidelines)
-5. [Automatic constant replacement](#automatic-constant-replacement)
-6. [Linking to Javadocs](#linking-to-javadocs)
-7. [Code of Conduct](#code-of-conduct)
+5. [Version tags](#version-tags)
+6. [Automatic constant replacement](#automatic-constant-replacement)
+7. [Linking to Javadocs](#linking-to-javadocs)
+8. [Code of Conduct](#code-of-conduct)
 
 ## Introduction
 
@@ -20,7 +21,7 @@ information, instructions, and guidelines to our users, developers, and contribu
 significant role in improving and maintaining the quality of our documentation.
 
 We use [Starlight](https://starlight.astro.build/) to build and deploy the documentation website.
-Docusaurus has [extensive documentation](https://starlight.astro.build/guides/authoring-content/) detailing what is possible with it.
+Starlight has [extensive documentation](https://starlight.astro.build/guides/authoring-content/) detailing what is possible with it.
 
 The bulk of Paper's documentation is written with Markdown, which is a simple markup language that is easy to learn.
 Take a look at some of the existing documentation to get a feel for how it is written.
@@ -97,6 +98,26 @@ To maintain consistency and readability across the documentation, please adhere
 
 11. **Capitalize Vanilla**: When referring to the base game, use "Vanilla" with a capital "V".
 
+## Version tags
+
+All of our documentation which is potentially relevant to a specific version of the software should be tagged with the
+`version` front matter value. This allows the user to see which version of the software the documentation was written for.
+
+It is important to keep this up to date, as it allows users to see if the documentation is still relevant to the version,
+however it is not required for all documentation. For example, a page about the history of the project would not need a
+`version` value.
+
+```markdown
+---
+title: My awesome page
+description: My awesome page about my awesome topic for 1.20.
+slug: paper/my-awesome-page
+version: "1.20"
+---
+
+.....
+```
+
 ## Automatic constant replacement
 
 There are quite a few constants you may want to use in your pages, such as the latest Paper/Velocity/Minecraft version.

_redirects

@@ -1,6 +1,12 @@
 /intro /
 /java-install-update /misc/java-install
 /papermc/* /misc/*
+/paper/1.18 /paper
+/paper/1.18/* /paper/*
+/paper/1.19 /paper
+/paper/1.19/* /paper/*
+/paper/1.20 /paper
+/paper/1.20/* /paper/*
 /velocity/developers/* /velocity/dev/*
 /velocity/dev/component-api/introduction /paper/dev/component-api/introduction
 /velocity/dev/component-api/i18n /paper/dev/component-api/i18n

astro.config.ts

@@ -43,6 +43,8 @@ export default defineConfig({
         Sidebar: "./src/components/overrides/Sidebar.astro",
         Footer: "./src/components/overrides/Footer.astro",
         Banner: "./src/components/overrides/Banner.astro",
+        TableOfContents: "./src/components/overrides/TableOfContents.astro",
+        MobileTableOfContents: "./src/components/overrides/MobileTableOfContents.astro",
       },
       plugins: [
         starlightLinksValidator({

src/components/Version.astro

@@ -0,0 +1,66 @@
+---
+import { Icon } from "@astrojs/starlight/components";
+
+interface Props {
+  version: string;
+  inline?: boolean;
+}
+
+const { version, inline } = Astro.props;
+---
+
+<div class:list={["notice", inline && "notice-inline"]}>
+  <Icon name="information" class="icon" />
+  <div class="notice-inner">
+    Written for version:
+    <span>{version}</span>
+  </div>
+</div>
+
+<style>
+  .icon {
+    font-size: var(--sl-text-3xl);
+  }
+
+  .notice {
+    display: flex;
+    flex-direction: row;
+    gap: 1rem;
+    align-items: center;
+    max-width: 14rem;
+    font-size: var(--sl-text-xs);
+    padding: 1rem;
+    border-radius: 0.5rem;
+    background-color: rgba(var(--sl-color-accent-raw), 0.125);
+    margin: 1rem 0;
+  }
+
+  .notice span {
+    font-weight: 600;
+    font-size: var(--sl-text-xl);
+  }
+
+  .notice .notice-inner {
+    display: flex;
+    flex-direction: column;
+  }
+
+  .notice-inline {
+    max-width: 100%;
+    margin: 0;
+    border-radius: 0;
+    font-size: var(--sl-text-sm);
+  }
+
+  .notice-inline span {
+    font-size: var(--sl-text-sm);
+  }
+
+  .notice-inline .icon {
+    font-size: var(--sl-text-lg);
+  }
+
+  .notice-inline .notice-inner {
+    display: block;
+  }
+</style>

src/components/overrides/MobileTableOfContents.astro

@@ -0,0 +1,9 @@
+---
+import Default from "@astrojs/starlight/components/MobileTableOfContents.astro";
+import Version from "../Version.astro";
+
+const { version } = Astro.locals.starlightRoute.entry.data;
+---
+
+<Default><slot /></Default>
+{version && <Version {version} inline />}

src/components/overrides/TableOfContents.astro

@@ -0,0 +1,9 @@
+---
+import Default from "@astrojs/starlight/components/TableOfContents.astro";
+import Version from "../Version.astro";
+
+const { version } = Astro.locals.starlightRoute.entry.data;
+---
+
+<Default><slot /></Default>
+{version && <Version {version} />}

src/content.config.ts

@@ -12,6 +12,7 @@ export const collections = {
             destructive: z.boolean().optional(),
           })
           .optional(),
+        version: z.string().optional(),
       }),
     }),
   }),

src/content/docs/paper/admin/reference/configuration/index.mdx

@@ -59,13 +59,11 @@ To set a value for a specific world, edit `paper-world.yml` within the world fol
 you wanted to enable `lootables.auto-replenish` for a world named `resource`, you would edit
 `paper-world.yml` within the `resource` folder like so:
 
-```yaml title=resource/paper-world.yml
+```yaml title=resource/paper-world.yml {3-4}
 _version: 28
 
-# highlight-start
 lootables:
   auto-replenish: true
-# highlight-end
 ```
 
 Nothing but `_version` is set in `paper-world.yml` configuration files by default. In order to

src/content/docs/paper/dev/api/command-api/basics/executors.md

@@ -45,14 +45,12 @@ which is relevant, if the command was ran via `/execute as <entity> run <our_com
 In the [Arguments and Literals](/paper/dev/command-api/basics/arguments-and-literals) chapter, we have briefly declared the structure for a `/flyspeed` command with the use of a ranged float argument.
 But that command does not actually set the flyspeed of the executing player. In order to do that, we'd have to append an executor onto it, like this:
 
-```java title="FlightSpeedCommand.java"
+```java title="FlightSpeedCommand.java" {5-6}
 Commands.literal("flyspeed")
     .then(Commands.argument("speed", FloatArgumentType.floatArg(0, 1.0f))
         .executes(ctx -> {
             float speed = FloatArgumentType.getFloat(ctx, "speed"); // Retrieve the speed argument
-            // highlight-next-line
             CommandSender sender = ctx.getSource().getSender(); // Retrieve the command sender
-            // highlight-next-line
             Entity executor = ctx.getSource().getExecutor(); // Retrieve the command executor, which may or may not be the same as the sender
 
             // Check whether the executor is a player, as you can only set a player's flight speed

src/content/docs/paper/dev/api/entity-api/display-entities.md

@@ -108,30 +108,26 @@ world.spawn(location, BlockDisplay.class, entity -> {
 
 You can also rotate it, let's tip it on its corner:
 
-```java
+```java {6, 8, 15-19}
 world.spawn(location, BlockDisplay.class, entity -> {
     entity.setBlock(Material.GRASS_BLOCK.createBlockData());
     entity.setTransformation(
         new Transformation(
                 new Vector3f(), // no translation
-                // highlight-next-line
                 new AxisAngle4f((float) -Math.toRadians(45), 1, 0, 0), // rotate -45 degrees on the X axis
                 new Vector3f(2, 2, 2), // scale up by a factor of 2 on all axes
-                // highlight-next-line
                 new AxisAngle4f((float) Math.toRadians(45), 0, 0, 1) // rotate +45 degrees on the Z axis
         )
     );
     // or set a raw transformation matrix from JOML
     // entity.setTransformationMatrix(
     //         new Matrix4f()
     //                 .scale(2) // scale up by a factor of 2 on all axes
-                       // highlight-start
     //                 .rotateXYZ(
     //                         (float) Math.toRadians(360 - 45), // rotate -45 degrees on the X axis
     //                         0,
     //                         (float) Math.toRadians(45) // rotate +45 degrees on the Z axis
     //                 )
-                       // highlight-end
     // );
 });
 ```
@@ -142,12 +138,11 @@ world.spawn(location, BlockDisplay.class, entity -> {
 
 Finally, we can also apply a translation transformation (position offset) to the display, for example:
 
-```java
+```java {5, 14}
 world.spawn(location, BlockDisplay.class, entity -> {
     entity.setBlock(Material.GRASS_BLOCK.createBlockData());
     entity.setTransformation(
         new Transformation(
-                // highlight-next-line
                 new Vector3f(0.5F, 0.5F, 0.5F), // offset by half a block on all axes
                 new AxisAngle4f((float) -Math.toRadians(45), 1, 0, 0), // rotate -45 degrees on the X axis
                 new Vector3f(2, 2, 2), // scale up by a factor of 2 on all axes
@@ -157,7 +152,6 @@ world.spawn(location, BlockDisplay.class, entity -> {
     // or set a raw transformation matrix from JOML
     // entity.setTransformationMatrix(
     //         new Matrix4f()
-                       // highlight-next-line
     //                 .translate(0.5F, 0.5F, 0.5F) // offset by half a block on all axes
     //                 .scale(2) // scale up by a factor of 2 on all axes
     //                 .rotateXYZ(

src/styles/custom.css

@@ -34,8 +34,11 @@
 
 /* Dark mode colors. */
 :root {
+  /* raw values for setting opacity */
+  --sl-color-accent-raw: 37, 99, 235;
+
   --sl-color-accent-low: #1e3a8a;
-  --sl-color-accent: #2563eb;
+  --sl-color-accent: rgb(var(--sl-color-accent-raw));
   --sl-color-accent-high: #60a5fa;
   --sl-color-white: #ffffff;
   --sl-color-gray-1: #e2e5e9;
@@ -52,8 +55,11 @@
 
 /* Light mode colors. */
 :root[data-theme="light"] {
+  /* raw values for setting opacity */
+  --sl-color-accent-raw: 37, 99, 235;
+
   --sl-color-accent-low: #60a5fa;
-  --sl-color-accent: #2563eb;
+  --sl-color-accent: rgb(var(--sl-color-accent-raw));
   --sl-color-accent-high: #1e3a8a;
   --sl-color-white: #111111;
   --sl-color-gray-1: #181a1b;