[improve][doc] Improve the links to reference docs with versions and anchors#459
Conversation
docs/admin-api-brokers.md
Outdated
| This page only shows **some frequently used operations**. | ||
|
|
||
| - For the latest and complete information about `Pulsar admin`, including commands, flags, descriptions, and more information, see [Pulsar admin doc](/tools/pulsar-admin/). | ||
| - For the latest and complete information about `Pulsar admin`, including commands, flags, descriptions, and more information, see [Pulsar admin doc](https://pulsar.apache.org/reference/#/@pulsar:version_origin@/pulsar-admin/). |
There was a problem hiding this comment.
I'd suggest use /reference/... or pathname:///reference so that we can locally debug (instead of always link to the online version).
There was a problem hiding this comment.
Did you mean that we can directly use pathname:// to replace the domain prefix https://pulsar.apache.org for all these occurrences?
There was a problem hiding this comment.
Good to know that. I can update them as long as the logic is stable:) Does it also apply to REST API links like https://pulsar.apache.org/admin-rest-api/?version=@pulsar:version_number@?
And do you know whether the built-in link checker can cover broken internal links like this?
There was a problem hiding this comment.
Does it also apply to REST API links
Yes.
whether the built-in link checker can cover broken internal links like this
I don't know. One case is that we may not bundle all static files, so it can produce false positives. But IIRC we bundle all recent versions.
There was a problem hiding this comment.
Said that for references, we bundle all pages: https://github.com/apache/pulsar-site/tree/main/static/reference
There was a problem hiding this comment.
I've applied this change to more occurrences containing https://pulsar.apache.org/, such as /download/, /api/admin/, /swagger/ and /admin-rest-api/.
docs/about.md
Outdated
| <BlockLink title="Get Started" url="/docs/next/getting-started-home" /> | ||
| <BlockLink title="Install, Deploy, Upgrade" url="/docs/next/install-deploy-upgrade-landing" /> | ||
| <BlockLink title="Pulsar for Developers" url="/docs/next/developers-landing" /> | ||
| <BlockLink title="How To" url="/docs/next/how-to-landing" /> |
There was a problem hiding this comment.
Shall we apply the relative path for these tags consistently also?
There was a problem hiding this comment.
You are right! Thanks for finding out more occurrences that I missed.
4 participants
Fixes apache/pulsar#19676.
This improvement is enabled by #456 and only applies to 2.8.x docs and later versions that are actively maintained.
Modifications
https://pulsar.apache.org/tools/withpathname:///reference/https://pulsar.apache.org/, like:/download/,/api/admin/,/swagger/and/admin-rest-api/....@pulsar:version_origin@to version-specific links to redirect with the expected doc version./docs/next/from several links.Note that
@pulsar:version_origin@is the variable used as doc version numbers of the reference doc site.//cc @Anonymitaet @DaveDuggins
Documentation
docdoc-requireddoc-not-neededdoc-complete