[Doc] Use the reference site (replacing tools) with versioned links

[momo-jun]

Search before asking

• I searched in the issues and found nothing similar.

What issue do you find in Pulsar docs?

The new reference site https://pulsar.apache.org/reference/ has been built, while up to 200 links are still pointing to the old tools site https://pulsar.apache.org/tools/ in the master branch.

Given that the user experience of the tools site has the following cons/inconvenience:

• The root/main page seems to be unfinished/unpolished.
• Inside the command pages, there is no anchor to locate a specific command directly.

What is your suggestion?

In the latest discussion, the consesus is we'd better:

1. replace the existing links https://pulsar.apache.org/tools/ with https://pulsar.apache.org/reference/
2. specify a link to a specific command for a particular Pulsar version.

The challenge of suggestion no.2 is to take the current version from the Docusaurus context (2.11.x) and convert it to the version used in reference documentation.

Any reference?

As @tisonkun pointed out in this comment, some functions in the pulsar-site code can handle versions with contextual pages when you search for versions in *.js and *.ts files.

Are you willing to submit a PR?

• I'm willing to submit a PR!

[dave2wave]

Please see #19681 as well - a lot may be broken with bad use of version=master

[Anonymitaet]

specify a link to a specific command for a particular Pulsar version.

It's not recommended to add a link for a specific command since it increases error possibilities and maintenance costs.

Instead, this case can be handled like below:

For xxx, see xxx command on the [Pulsar Reference Site](https://pulsar.apache.org/reference).

[momo-jun]

@Anonymitaet What you mentioned is an intermediate/compromised solution since we currently don't have a way to process the reference site links with variable versions.

Just like the REST API doc site processes the links with variable versions. We expect to use anchored links to go to a specific command in the expected doc version of the reference site. This issue logs this expectation to maximize the value of the reference site and eliminate the current limitation. The potential solution (if there is a way) should not involve increased error possibilities and maintenance costs.

[momo-jun]

Ping @urfreespace to take a look at this request. Can we implement a similar script to enable the links pointing to the reference site (https://pulsar.apache.org/reference/) to anchor specific commands under a designated doc version, as we did for REST API links in the src/utils/index.js file?

[urfreespace]

Ping @urfreespace to take a look at this request. Can we implement a similar script to enable the links pointing to the reference site (https://pulsar.apache.org/reference/) to anchor specific commands under a designated doc version, as we did for REST API links in the src/utils/index.js file?

apache/pulsar-site#456 PTAL

[momo-jun]

@urfreespace, thanks very much! This enablement doubles the power and efficiency of the new references site!
I will update more occurrences as soon as your script is merged.