[nchammas]

What changes were proposed in this pull request?

Upgrade AnchorJS to v5.0.0, and update its config accordingly to maintain roughly the current production behavior.

Additionally:

• Move the AnchorJS config to global.html, which matches where we include and configure other vendored libraries.
• Remove the anchors global from main.js, which is no longer needed now that the config is handled outside of there.
• Fix the included licenses for AnchorJS so it includes the copyright holder's name and year.

Why are the changes needed?

The current version of AnchorJS we are using is more than 11 years old. The releases since then have added more accessible heading links and more reliable fragment generation.

This upgrade will also keep the versions in sync with the main website's version of AnchorJS: apache/spark-website#700

Any browser released since early 2021 should support this new version without issue.

Does this PR introduce any user-facing change?

No, documentation behavior tweaks only.

How was this patch tested?

I built and reviewed the site locally with SKIP_API=1 bundle exec jekyll serve. Confirmed that anchors work as expected, including for h1 headings.

Was this patch authored or co-authored using generative AI tooling?

Co-authored-by: GitHub Copilot

[HyukjinKwon]

(the label is still under dev .. I will likely be able to enable it this week)

[HyukjinKwon]

LGTM

[uros-b]

+1, thank you @nchammas and @HyukjinKwon!

[dongjoon-hyun]

Thank you for the upgrade, @nchammas. I reviewed the latest commit, 3a8ed3d, and left 9 inline comments. Here is a summary, ordered by priority.

Correctness and compatibility

1. licenses-binary/LICENSE-AnchorJS.txt L3: the copyright fix is not applied to the binary copy, which the binary tarball and the pyspark package ship.
2. global.html L209: the page-wide selector also anchors the sidebar <h3> titles and the hero <h1> (not a regression), so the titles of 7 streaming pages get -1 ids; scoping it to #content would fix this.
3. global.html L209: right after a release, a browser with the old main.js and 1.1.1 still cached can add every anchor twice.
4. anchor.min.js L8: the bare globalThis drops all anchors on Chrome < 71, Firefox < 65, and Safari < 12.1 (negligible in practice).

Maintainability

5. global.html L206: the inline config is not covered by dev/lint-js, unlike the same lines in main.js.
6. global.html L199: the sync note sits in the ignored body of <script src>, and its link returns 404 until apache/spark-website#700 is merged.

PR title and description

7. Title: [INFRA] maps to Project Infra, but docs front-end changes have used [DOCS]; AnchorJS itself was added as [SPARK-8353] [DOCS]. Could the title be [SPARK-60281][DOCS] Upgrade AnchorJS to v5.0.0, with the JIRA component to match?
8. Description: the generative-AI section does not have the Generated-by: <tool> <version> phrase that the PR template asks for, e.g. Generated-by: GitHub Copilot <version>, and "AnchorsJS" is a typo. Both end up in the commit message.

Optional

9. global.html L206: placement: 'right' is the default, so the line has no effect.
10. anchor.min.js L8: FYI, 5.0.0 queries <base> once per heading (an upstream issue).
11. main.js L100: pre-existing and outside this PR: the resize handler keeps re-binding the dropdown hover handlers.

Items 1, 2, and 5 are the ones I would most like to see addressed here, and items 7 and 8 only need the PR title and description. The rest are optional.

[dongjoon-hyun]

2. This selector also anchors the layout's own headings, not just the page content. It matches the fixed sidebar titles from _includes/nav-left-wrapper-*.html (for example <h3><a href="sql-programming-guide.html">Spark SQL Guide</a></h3>) and the hero <h1> on the landing page. As a result:

• On the 151 sql*.html pages, the sidebar title gets an anchor to #spark-sql-guide on the current page, and screen readers read one more "Anchor" link there.
• On the 7 streaming pages titled "Structured Streaming Programming Guide", the sidebar <h3> comes first in DOM order, so it takes #structured-streaming-programming-guide, and the real page title gets #structured-streaming-programming-guide-1.

This is not a regression, because 1.1.1's default selector matched the same elements. But since this line is being rewritten anyway, could we scope it to the content? Both layout branches use id="content", so anchors.add('#content h1, #content h2, #content h3, #content h4, #content h5, #content h6'); keeps the page-title and section anchors and drops the sidebar and hero ones.

[nchammas]

Addressed. I used the more modern :is CSS selector here, as it's cleaner. Any browser released since early 2021 will support it.

[dongjoon-hyun]

3. Minor: moving this call out of main.js can briefly double the anchors right after a release. spark.apache.org serves docs/latest/js/*.js with only Last-Modified and ETag, without Cache-Control or Expires, so browsers may keep reusing cached copies for days after docs/latest moves to a new release. A returning visitor who still has the old main.js and the 1.1.1 anchor.min.js cached runs this new anchors.add(...) first and the old anchors.add() in main.js second. 1.1.1 has no check for an existing anchor, so every heading shows two icons until the cache expires. It is cosmetic and temporary. Could we keep the call in main.js as in item 5, which avoids this mixed state?

[nchammas]

Don't think this is worth any cache-busting fixes. It's a minor and transient issue, as you noted. I will address item 5 separately.

[dongjoon-hyun]

4. Minor: 5.0.0 passes a bare globalThis to its UMD wrapper here, unlike 1.1.1 (plain ES5) and our Bootstrap 5.0.2 bundle (which checks typeof globalThis). On Chrome < 71, Firefox < 65 (including ESR 60), and Safari < 12.1, which Bootstrap 5.0.2's .browserslistrc still lists, this line throws ReferenceError: globalThis is not defined. Then global.html:206 throws anchors is not defined, and those browsers get no heading anchors at all. The rest of the page still works, because the config runs in its own <script>. These browsers have been out of support for years, so accepting this is fine with me. Could you mention it in the PR description, or add if (typeof globalThis === 'undefined') { window.globalThis = window; } before this script if you want to keep them working?

[nchammas]

Chrome < 71, Firefox < 65 (including ESR 60), and Safari < 12.1

These browser versions date to early 2019 at the latest. I don't think code changes to support them are merited. I will update the PR description.

[dongjoon-hyun]

5. Minor: moving these lines out of docs/js/main.js also takes them out of the lint check. dev/lint-js runs ESLint (eslint:recommended, which includes no-undef) on docs/js only, and nothing lints docs/_layouts. So a later typo here, such as anchros.add(...), would pass CI and silently remove the anchors from every page, while the same typo in main.js fails no-undef (which is why main.js declared /* global $, anchors */). A separate ready handler in main.js keeps both the lint check and the isolation you get from a separate script, because jQuery 3.7.1 runs each ready handler in its own promise chain, so an error in one does not skip the dropdown setup in the other:

$(function() {
  anchors.options = { placement: 'right' };
  anchors.add('h1, h2, h3, h4, h5, h6');
});

Could you move the config back into main.js this way and restore /* global $, anchors */?

[nchammas]

We already include other libraries in global.html, like jQuery, MathJax, and DocSearch, which is why I moved AnchorJS there. I think the correct fix here is in a follow-up PR to add HTML linting via eslint-plugin-html.

[dongjoon-hyun]

10. Nit: FYI, 5.0.0's add() calls document.querySelector('base') inside its per-heading loop (anchor.js L140 at tag 5.0.0). Our pages have no <base>, so each heading triggers a scan of the whole document. On the largest page, sql-ref-functions-builtin.html (about 1.5 MB, ~48K elements, 48 headings), that is about 48 extra scans during parsing. I have not measured it, but it should be a few milliseconds. Nothing to change here, since this file should stay identical to upstream. Could it be worth an upstream issue to move that query out of the loop?

[nchammas]

I haven't looked into this. I think a future, dedicated performance analysis of the website would likely find higher-impact improvements we could make. At that time, we can pursue upstream fixes as needed.

[dongjoon-hyun]

11. Nit: this is pre-existing and outside this PR. The dropdown block below (L100-L119) calls $dropdown.hover(...) again on every load or resize event at 768px or wider, without unbinding the previous handlers. jQuery's hover() is just .on("mouseenter", ...).on("mouseleave", ...), so the handlers pile up until the window becomes narrower than 768px. They are idempotent, so this only wastes work. The 768px threshold also differs from the navbar's navbar-expand-lg breakpoint (992px). This dates from SPARK-30654. Could $dropdown.off("mouseenter mouseleave").hover(...) go into a small follow-up?

[nchammas]

• Title: [INFRA] maps to Project Infra, but docs front-end changes have used [DOCS]; AnchorJS itself was added as [SPARK-8353] [DOCS]. Could the title be [SPARK-60281][DOCS] Upgrade AnchorJS to v5.0.0, with the JIRA component to match?

Done.

• Description: the generative-AI section does not have the Generated-by: <tool> <version> phrase that the PR template asks for, e.g. Generated-by: GitHub Copilot <version>, and "AnchorsJS" is a typo. Both end up in the commit message.

I think Generated-by: is too strong a label to use given that I authored this PR. I use AI assistance, yes, but Generated-by: indicates that some AI tool generated the patch, which is not correct.

I've submitted #59666 for our PR template to match ASF's guidance in suggesting Co-authored-by:, which is more appropriate in this case.