This is an automated email from the ASF dual-hosted git repository. lhotari pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/pulsar-site.git
commit d0fa60d0eeb82550a0b6469c2f5820f319676a2e Author: Lari Hotari <[email protected]> AuthorDate: Fri Apr 24 12:36:46 2026 +0300 In client-libraries, use latest version for @pulsar:.*@ version replacements, not "next" --- contribute/site-intro.md | 20 ++++++++++---------- src/config/pulsarVariables.ts | 9 +++++++-- src/server/markdownPreprocessors/pulsarVariables.ts | 4 +++- 3 files changed, 20 insertions(+), 13 deletions(-) diff --git a/contribute/site-intro.md b/contribute/site-intro.md index 0016592b677..441a42f03a7 100644 --- a/contribute/site-intro.md +++ b/contribute/site-intro.md @@ -97,16 +97,16 @@ The `<X>` segment is looked up in `versions.json` / the REST API version map. `. #### Version numbers -| Token | Expands to | -|--------------------------------|-----------------------------------------------------------------------------------------------------------------------| -| `@pulsar:version@` | Resolved semver version (e.g. `4.2.0`) — the latest patch of the minor line in context. | -| `@pulsar:version_number@` | Same as `@pulsar:version@` but with any trailing `-incubating` suffix stripped (only matters for very old versions). | -| `@pulsar:version_origin@` | The origin version key (e.g. `4.2.x` for released docs, full resolved version for current docs). | -| `@pulsar:version_reference@` | The folder name in `static/reference/` — `next` for current docs, `<major>.<minor>.x` otherwise. | -| `@pulsar:version:latest@` | Latest version across all releases (context-independent). | -| `@pulsar:version:lts@` | Current LTS version. Kept in sync with `ltsMajorRelease` in `pulsarVariables.ts`. | -| `@pulsar:version:adapters@` | Latest `pulsar-adapters` release, sourced from `data/release-pulsar-adapters.js`. | -| `@pulsar:version:python@` | Version of the Python client that matches the current context. | +| Token | Expands to | +|------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------| +| `@pulsar:version@` | Resolved semver version (e.g. `4.2.0`) — the latest patch of the minor line in context. | +| `@pulsar:version_number@` | Same as `@pulsar:version@` but with any trailing `-incubating` suffix stripped (only matters for very old versions). | +| `@pulsar:version_origin@` | The origin version key (e.g. `4.2.x` for released docs, full resolved version for current docs). | +| `@pulsar:version_reference@` | The folder name in `static/reference/` — `next` for `docs/`, latest release's `<major>.<minor>.x` for `client-libraries/`, `<major>.<minor>.x` otherwise. | +| `@pulsar:version:latest@` | Latest version across all releases (context-independent). | +| `@pulsar:version:lts@` | Current LTS version. Kept in sync with `ltsMajorRelease` in `pulsarVariables.ts`. | +| `@pulsar:version:adapters@` | Latest `pulsar-adapters` release, sourced from `data/release-pulsar-adapters.js`. | +| `@pulsar:version:python@` | Version of the Python client that matches the current context. | #### Release download URLs diff --git a/src/config/pulsarVariables.ts b/src/config/pulsarVariables.ts index f0e730447d6..ac18cc1dac3 100644 --- a/src/config/pulsarVariables.ts +++ b/src/config/pulsarVariables.ts @@ -148,8 +148,13 @@ export function referenceVersion(version: string): string { * * Keys are the bare token names (e.g. `"version_number"`, `"javadoc:client"`); * the preprocessor wraps them as `@pulsar:<key>@` when matching. + * + * `referenceLatest`: when true (used for `client-libraries/` docs), `version_reference` + * resolves to the latest stable release's reference (e.g. `4.2.x`) instead of `next`, + * so links like `/reference/#/@pulsar:version_reference@/client/` target the published + * reference rather than the in-development one. */ -export function resolveTokens(versionKey: string): Map<string, string> { +export function resolveTokens(versionKey: string, referenceLatest = false): Map<string, string> { const isCurrent = versionKey === "current"; const originVersion = isCurrent ? latestMajorRelease : versionKey; const resolvedVersion = getRealVersion(originVersion); @@ -159,7 +164,7 @@ export function resolveTokens(versionKey: string): Map<string, string> { // - versioned docs: version_number strips any -incubating suffix const versionNumber = isCurrent ? resolvedVersion : resolvedVersion.replace("-incubating", ""); const versionOrigin = isCurrent ? resolvedVersion : originVersion; - const versionReference = isCurrent ? "next" : referenceVersion(resolvedVersion); + const versionReference = isCurrent && !referenceLatest ? "next" : referenceVersion(resolvedVersion); const pythonArg = isCurrent ? originVersion : resolvedVersion; return new Map<string, string>([ diff --git a/src/server/markdownPreprocessors/pulsarVariables.ts b/src/server/markdownPreprocessors/pulsarVariables.ts index 7c41d1233e2..4b3638f0940 100644 --- a/src/server/markdownPreprocessors/pulsarVariables.ts +++ b/src/server/markdownPreprocessors/pulsarVariables.ts @@ -8,12 +8,14 @@ import {resolveTokens} from "../../config/pulsarVariables"; // @pulsar:version:*@ / @pulsar:apidoc:*@ variables as the main docs set. const SCOPE_RE = /(?:^|[/\\])(?:docs|client-libraries|versioned_docs[/\\]version-[^/\\]+)[/\\].*\.md$/; const VERSIONED_RE = /(?:^|[/\\])versioned_docs[/\\]version-([^/\\]+)[/\\]/; +const CLIENT_LIBRARIES_RE = /(?:^|[/\\])client-libraries[/\\]/; const TOKEN_RE = /@pulsar:([^@\s]+)@/g; type Args = {filePath: string; fileContent: string}; export function replacePulsarTokens(fileContent: string, versionKey: string, filePath?: string): string { - const tokens = resolveTokens(versionKey); + const referenceLatest = filePath !== undefined && CLIENT_LIBRARIES_RE.test(filePath); + const tokens = resolveTokens(versionKey, referenceLatest); const warned = new Set<string>(); return fileContent.replace(TOKEN_RE, (match, key: string) => { const value = tokens.get(key);
