lhotari opened a new pull request, #1132:
URL: https://github.com/apache/pulsar-site/pull/1132
## Summary
Implements the approach described in #1131: moves all `client-libraries-*`
documentation to a single unversioned location at `/docs/client-libraries/`,
eliminating the 33× duplication of these pages across `versioned_docs/`.
- **New unversioned content-docs plugin** at `routeBasePath:
"docs/client-libraries"`, seeded from `version-4.2.x/`. 36 pages moved and
renamed to drop the redundant `client-libraries-` prefix (e.g.
`client-libraries-python.md` → `python.md`).
- **Deleted 508 legacy files** — 36 from `docs/` plus 472 across all 33
`versioned_docs/version-*/` directories. Legacy URLs redirect via
`static/.htaccess` (regex-based, covers every version × slug pair in one rule)
and `@docusaurus/plugin-client-redirects` entries for dev-mode and static-host
preview.
- **Trimmed sidebars** — replaced the 'Client Libraries' category in
`sidebars.json` and all 33 `versioned_sidebars/version-*.json` files with a
single outbound link pointing at `/docs/client-libraries/`.
- **Merged** `/client-feature-matrix/` into the same plugin as
`feature-matrix` so it inherits the client-libraries sidebar. Old URL redirects.
- **Sidebar layout** — wraps everything in a top-level 'Client Libraries'
category whose link target is the overview doc (via `slug: /` on
`overview.md`), so `/docs/client-libraries/` serves the overview and
breadcrumbs include 'Client Libraries'. No 'Overview' leaf is rendered.
- **Hide version picker + banner** on `/docs/client-libraries/*` pages —
they're unversioned, so the 'Version: Next' dropdown and 'unreleased version'
banner no longer apply.
- **Preprocessor variables** — `pulsarVariablesPreprocessor` scope extended
to include `client-libraries/`, so `@pulsar:version@`, `@pulsar:apidoc:cpp@`
etc. expand correctly in the moved content. Also added two new vars,
`@pulsar:version:lts@` and `@pulsar:version:latest@`, to
`src/config/pulsarVariables.ts`.
- **Java page defaults to LTS** — `client-libraries/java.md` and
`client-libraries/java-setup.md` use `@pulsar:version:lts@` in Maven/Gradle
install snippets. Intro explicitly mentions both the LTS version and the most
recent version.
- **Build fixes**:
- Guarded the swizzled `DocsVersionDropdownNavbarItem` against undefined
`activeDocContext.activeDoc` (SSG crashed on every `/docs/client-libraries/*`
route without this).
- Added `description:` frontmatter to `java.md` so Docusaurus' meta-tag
auto-extractor doesn't strip colons from `@pulsar:version:lts@` into
`@pulsarlts@`.
## Verification
- `npm run build` — exits 0. 4 warnings, 0 errors.
- Zero unexpanded `@pulsar:*@` variables in the built HTML for any
`build/docs/client-libraries/` page.
- `/docs/client-libraries/feature-matrix/` serves with the full
client-libraries sidebar.
- `/docs/client-libraries/java/` contains no `sidebarVersionSwitch` or
`docVersionBanner` markup; `/docs/next/concepts-overview/` still renders both,
so the suppression is scoped correctly.
- Breadcrumb structured data on `/docs/client-libraries/java/`: `Client
Libraries → Java client`.
- `/client-feature-matrix/` emits a `<meta http-equiv=refresh>` redirect
stub to the new URL.
Remaining broken-link warnings after this change are all pre-existing
content issues (blog posts pointing at old-style `/docs/client-libraries-*`
URLs — handled by `.htaccess` in prod — and anchor-id mismatches like
`#producer-configuration` vs `## Producer configs` headings in the source).
Verified via `git show
main:versioned_docs/version-4.2.x/client-libraries-node-use.md` that these
pre-date the migration.
## Test plan
- [ ] `npm run build` succeeds locally
- [ ] Spot-check `/docs/client-libraries/` renders the overview with the new
sidebar
- [ ] Spot-check `/docs/client-libraries/java` shows LTS version in Maven
coordinates
- [ ] Spot-check breadcrumbs on a deep page include 'Client Libraries'
- [ ] Spot-check a legacy URL like `/docs/4.1.x/client-libraries-python`
redirects to `/docs/client-libraries/python` (requires staging / `.htaccess`
active)
Closes #1131 on merge, or at least moves the conversation from the
open-question stage to an implemented direction.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
