fix: bukkit.yml settings.minimum-api, pass MD config to on-demand renderer

Fixes #586.

Author: zlataovce

CONTRIBUTING.md

@@ -160,6 +160,12 @@ loader: io.papermc.testplugin.TestPluginLoader
 ```
 ````
 
+For inline code blocks, i.e. `my code block` (`` `my code block` `` in Markdown), you do not need to use a property - replacements are done for all inline code blocks.
+
+```markdown
+- `api-version: '\{LATEST_PAPER_RELEASE}'`
+```
+
 ## Linking to Javadocs
 
 Many Javadoc sites support a `latest` tag, such as javadoc.io or similar, in which case, just use that in a plain Markdown link.

astro.config.ts

@@ -394,6 +394,15 @@ export default defineConfig({
       pad: 50,
       skipGeneration: !prod, // comment out if you have D2 locally and want to use it during dev
     }),
+    // save Markdown renderer configuration to globals for use by the on-demand renderer
+    {
+      name: "docs:config-md",
+      hooks: {
+        "astro:config:done": ({ config }) => {
+          globalThis.markdownConfig = config.markdown;
+        },
+      },
+    },
   ],
   build: {
     inlineStylesheets: "always",

package.json

@@ -30,6 +30,7 @@
     "yaml": "^2.7.1"
   },
   "devDependencies": {
+    "@types/mdast": "^4.0.4",
     "@types/node": "^22.14.1",
     "prettier": "3.5.3",
     "prettier-plugin-astro": "0.14.1",

pnpm-lock.yaml

@@ -44,7 +44,7 @@ settings:
     default: none
     description: >
       Minimum plugin [api-version](/paper/dev/plugin-yml#api-version). A string
-      containing the server version, ignoring minor part, from 1.13 to 1.20. If
+      containing the server version, from `1.13` to `\{LATEST_PAPER_RELEASE}`. If
       below this, or not specified, the plugin is prevented from loading.
   use-map-color-cache:
     default: "true"

src/config/paper/bukkit.yml

@@ -94,7 +94,7 @@ This will be shown in the plugin info commands.
 The version of the Paper API that your plugin is using. This doesn't include the minor version until 1.20.5. From 1.20.5 and onward, a minor version is supported.
 Servers with a version lower than the version specified here will refuse to load the plugin.
 The valid versions are 1.13 - {LATEST_PAPER_RELEASE}.
-- <code>api-version: '{LATEST_PAPER_RELEASE}'</code>
+- `api-version: '\{LATEST_PAPER_RELEASE}'`
 
 :::note
 

src/content/docs/paper/dev/getting-started/plugin-yml.mdx

@@ -0,0 +1,6 @@
+import type { AstroMarkdownOptions } from "@astrojs/markdown-remark";
+
+declare global {
+  // for passing the Markdown configuration to the on-demand renderer
+  var markdownConfig: AstroMarkdownOptions;
+}

src/env.d.ts

@@ -1,6 +1,6 @@
 import { createMarkdownProcessor } from "@astrojs/markdown-remark";
 
-const renderer = await createMarkdownProcessor();
+const renderer = await createMarkdownProcessor(globalThis.markdownConfig);
 
 export const render = async (content: string): Promise<string> => {
   const code = (await renderer.render(content)).code;

src/utils/markdown.ts

@@ -1,4 +1,5 @@
 import type { RemarkPlugin } from "@astrojs/markdown-remark";
+import type { Literal } from "mdast";
 import { visit } from "unist-util-visit";
 
 // replaces constants in code blocks
@@ -10,12 +11,13 @@ interface Options {
 
 const plugin: RemarkPlugin = ({ constants }: Options) => {
   return (tree) => {
-    visit(tree, "code", (node) => {
-      if (!node.meta?.includes("replace")) {
+    visit(tree, ["code", "inlineCode"], (node) => {
+      if (node.type === "code" && !node.meta?.includes("replace")) {
         return;
       }
 
-      node.value = node.value.replace(/\\\{([^}]+?)}/g, (_, name) => constants[name] ?? name);
+      const code = node as Literal;
+      code.value = code.value.replace(/\\\{([^}]+?)}/g, (_, name) => constants[name] ?? name);
     });
   };
 };