Replace scripts/replace.js with a Docusaurus markdown preprocessor

Move the @Pulsar:...@ token expansion and the {@Inject:...} link expansion
out of a standalone post-processing script / inline config block into two
focused preprocessor modules under src/server/markdownPreprocessors/. The
new pulsarVariables preprocessor scopes itself by filePath to docs/ and
versioned_docs/version-*/, preserving the exact scope of the old script
while making replacements visible during `yarn start` (previously only
applied in CI). Computed version/URL helpers are centralized in
src/config/pulsarVariables.ts so React components can consume them
directly without needing a separate replacement pass. Drops the
replace-in-file dependency and the node invocation from site_builder.py.
Also adds @Pulsar:version:adapters@.

BUILD_ALL_VERSION=1

Author: lhotari

README.md

@@ -33,6 +33,21 @@ After committing the changes for the `docs` directory, you can use the `docs-too
 ./scripts/docs-tool.sh apply_changes_to_versioned_docs
 ```
 
+## Markdown placeholders
+
+Markdown files under `docs/` and `versioned_docs/version-*/` are run through
+two preprocessors at build time:
+
+- `@pulsar:version@`, `@pulsar:rpm:client@`, `@pulsar:apidoc:python@`, etc. —
+  version-aware tokens. The values come from `versions.json`, `site-baseurls.js`,
+  and `data/release-*.js`. See `src/config/pulsarVariables.ts` for the full list.
+- `{@inject:javadoc:Name:org/...}`, `{@inject:endpoint|GET|/admin/...}` — link
+  expansion for Javadoc, GitHub, REST endpoints. See
+  `src/server/markdownPreprocessors/inject.ts`.
+
+To reference the same values from React components, import from
+`@site/src/config/pulsarVariables` — no placeholder is needed in `.js`/`.tsx`.
+
 ## More information
 
 * [Pulsar Website contribution guide](https://pulsar.apache.org/contribute/site-intro/)

docs/reference-configuration.md

@@ -4,4 +4,4 @@ title: Pulsar Configuration
 sidebar_label: "Pulsar Configuration"
 ---
 
-For a complete list of Pulsar configuration, visit the [Pulsar Reference](pathname:///reference/#/@pulsar:version_reference@/) website.
+For a complete list of Pulsar configuration, visit the <a href="pathname:///reference/#/@pulsar:version_reference@/" target="_blank" rel="noopener noreferrer">Pulsar Reference</a> website.

docusaurus.config.ts

@@ -28,99 +28,15 @@ try {
 }
 
 const {
-  siteUrl,
-  javadocUrl,
-  restApiUrl,
-  functionsApiUrl,
-  sourceApiUrl,
-  sinkApiUrl,
-  packagesApiUrl,
-  transactionsApiUrl,
-  lookupApiUrl,
-  githubUrl,
   githubSiteUrl,
   baseUrl,
-  restApiBaseUrlMapping
+  restApiBaseUrlMapping,
 } = require("./site-baseurls");
 
-const injectLinkParse = (prefix, name, path) => {
-  if (prefix == "javadoc") {
-    return {
-      link: javadocUrl + path,
-      text: name,
-    };
-  } else if (prefix == "github") {
-    return {
-      link: githubUrl + "/tree/master/" + path,
-      text: name,
-    };
-  } else if (prefix == "rest") {
-    return {
-      link: restApiUrl + "#" + path,
-      text: name,
-    };
-  } else if (prefix == "functions") {
-    return {
-      link: functionsApiUrl + "#" + path,
-      text: name,
-    };
-  } else if (prefix == "source") {
-    return {
-      link: sourceApiUrl + "#" + path,
-      text: name,
-    };
-  } else if (prefix == "sink") {
-    return {
-      link: sinkApiUrl + "#" + path,
-      text: name,
-    };
-  } else if (prefix == "packages") {
-    return {
-      link: packagesApiUrl + "#" + path,
-      text: name,
-    };
-  }
-
-  return {
-    link: path,
-    text: name,
-  };
-};
-
-const injectLinkParseForEndpoint = (info) => {
-  let [method, path, suffix] = info.split("|");
-
-  if (!suffix) {
-    suffix = "";
-  }
-
-  let restPath = path.split("/");
-  const restApiVersion = restPath[2];
-  const restApiType = restPath[3];
-  const restBaseUrl = restApiBaseUrlMapping[restApiType] || restApiUrl;
-
-  let restUrl;
-  if (suffix.indexOf("?version=") >= 0) {
-    const suffixAndVersion = suffix.split("?version=")
-    restUrl = "version=" + suffixAndVersion[1] + "&apiversion=" + restApiVersion + "#" + suffixAndVersion[0];
-    if (suffixAndVersion[0].startsWith("operation/")) {
-      path += suffixAndVersion[0].slice("operation".length)
-    }
-  } else {
-    restUrl = "version=master&apiversion=" + restApiVersion + "#" + suffix;
-    if (suffix.startsWith("operation/")) {
-      path += suffix.slice("operation".length)
-    }
-  }
-
-  return {
-    text: method + " " + path,
-    link: restBaseUrl + "?" + restUrl,
-  };
-};
-
 /** @type {import('@docusaurus/types').Config} */
 module.exports = async function createConfigAsync() {
+  const injectPreprocessor = (await import("./src/server/markdownPreprocessors/inject")).default;
+  const pulsarVariablesPreprocessor = (await import("./src/server/markdownPreprocessors/pulsarVariables")).default;
   return {
     future: {
       faster: {
@@ -147,21 +63,10 @@ module.exports = async function createConfigAsync() {
       hooks: {
         onBrokenMarkdownLinks: "warn",
       },
-      preprocessor: ({ filePath, fileContent }) => {
-        return fileContent.replaceAll(/{@inject:([^}]+)}/g, (_, p1) => {
-          const p1Trimmed = p1.trim();
-          const endpointPrefix = 'endpoint|';
-          let link, text;
-          if (p1Trimmed.startsWith(endpointPrefix)) {
-            // @ts-ignore
-            ({ link, text } = injectLinkParseForEndpoint(p1Trimmed.substring(endpointPrefix.length)));
-          } else {
-            const [prefix, name, path] = p1Trimmed.split(':');
-            ({ link, text } = injectLinkParse(prefix, name, path));
-          }
-          return `[${text}](${link})`; // Format as a markdown link
-        });
-      },
+      preprocessor: (args) => injectPreprocessor({
+        ...args,
+        fileContent: pulsarVariablesPreprocessor(args),
+      }),
     },
     themes: ['@docusaurus/theme-mermaid'],
     themeConfig:

package.json

@@ -60,7 +60,6 @@
     "react-svg": "^16.1.34",
     "rehype-katex": "^7.0.1",
     "remark-math": "^6.0.0",
-    "replace-in-file": "6.3.2",
     "search-insights": "^2.17.3",
     "semver": "^7.7.4",
     "sine-waves": "^0.3.0",