Footnote links no longer working properly

[frankhecker]

Environment

I am using Minimal Mistakes 4.15.2 and Jekyll 3.8.5, recently upgraded from 4.12.0 and 3.8.3 respectively. For more information see the attached Gemfile.lock files for the old and new environments.

Gemfile.lock-old.txt
Gemfile.lock-new.txt

Expected behavior

In pages generated under the old environment Markdown footnote links behaved as expected: clicking on a footnote numeral link in text would cause the page to scroll to the footnote in question. Once there, clicking on the reverse link arrow would cause the scroll back to the original place where the footnote was referenced.

In pages generated under the new environment this behavior is broken: clicking on either the forward link or revise link causes the page to scroll to the top.

I have tested this under Safari 12.0.3, Firefox 65.01, and Chrome 72.0.3626.121 on MacOS Mojave. All show the same incorrect behavior.

Steps to reproduce the behavior

You can compare the behavior of the old and new generated pages by looking at the following two pages, the first one on my production server generated under MM 4.12.0, and the second on my staging server generated under MM 4.15.2; the underlying Markdown for the pages is unchanged from one to the other:

OLD: https://civilityandtruth.com/2018/03/22/seven-answers-social-democracy/
NEW: http://frankhecker.net/2018/03/22/seven-answers-social-democracy/

Other

If and when I have time I will try to create a minimal reproducible test case. The generated HTML for the pages themselves doesn't seem to differ in the HTML code for the footnotes, so it's possible the problem is in the included CSS files.

[frankhecker]

Update: The problem appears to be somewhere in main.min.js. If I modify assets/js on my staging server to replace the new MM 4.15.2 version of main.min.js with the old MM 4.12.0 then the problem goes away (after clearing browser cache and reloading the page in question). Similarly, if I replace the old 4.12.0 version of main.min.js on my production server with the new 4.15.2 version, the problem occurs (again, after clearing browser cache and reloading the page).

If I have time later I'll try to narrow down which line(s) in main.min.js appear to be causing the problem.

[frankhecker]

Update 2: I've narrowed this down further, by forcing use of a particular version of MM in the Gemfile on my staging server (frankhecker.net), doing a bundle update, regenerating the entire site from scratch, and then using the test page linked to above. (I don't use incremental update because in the past I've had problems with one of the plugins when I do that.)

I've determined that 4.14.2 is the last version for which footnote links work properly. Apparently one of the changes introduced in main.min.js for 4.15.0 broke footnote links.

I don't have time right now to debug this further. For now I'm going to stay on 4.14.2 until/unless someone finds a fix for this.

P.S. That means the test page above will not show the incorrect behavior. You can see it yourself by creating a page using Markdown footnote links and then generating it both in 4.14.2 and 4.15.0.

[mmistakes]

I haven’t tested this yet, but seeing how it seems to have broken in 4.15 and up, it is likely related to #2019 and #2023.

Ccing @edemaine as they did this work and might have some insight as to the issue.

[mmistakes]

I've confirmed that this is definitely a bug.

Perhaps dropping jQuery Smooth Scroll, the custom hash rewriting, and scrollspy implementation and going with Smooth Scroll + Gumshoe as noted in #2050 would be a better solution. Seems that it doesn't break footnote links.

[mmistakes]

I put up a proof of concept that fixes the issue by using Smooth Scroll + Gumshoe. It needs some work yet as the scrollspy .active classes trigger as you scroll to a header, but turns off as you scroll pass it.

To test out the PR brand you can replace gem "minimal-mistakes-jekyll" in your Gemfile with the following:

gem 'minimal-mistakes-jekyll', :git => 'https://github.com/mmistakes/minimal-mistakes.git', :branch => 'smooth-scroll-gumshoe'

[frankhecker]

The change you made appears to fix the problem with footnotes, at least on the browsers I tested: Chrome, Firefox, and Safari for MacOS (for versions see above) and Safari on iOS 12.1.4.

However I will note that on Chrome scrolling to the footnote and from the footnote back to the original test seems slower than normal with the fix; there is a noticeable lag until scrolling starts. (I didn't notice any substantial difference with the other browsers.)

Thanks for working on this!

[mmistakes]

The delay is part of the new Smooth Scroll script. It has different easing settings that I haven't tried adjusting yet to fine tune the scroll speed.

[edemaine]

Sorry I haven't had a chance to look this over yet (a busy week) but thanks @mmistakes for taking the lead here! Relying more on off-the-shelf packages seems like a generally good idea, so I'm happy to see this in the works. If you let me know when you tweak the settings, I'm happy to take the second testdrive.

[mmistakes]

Sounds good @edemaine. I'm struggling with getting Gumshoe's scroll spy to work correctly. So if you have any suggestions please let me know.

Seems like it was designed to have the anchor id on a <div> element wrapped around each TOC section. So what happens is the scrollspy hits a header with an id that matches the TOC link, activates the active class, but turns it off as soon as you scroll by the header.

I'm sure there's a way to keep it active until you hit the next id, but haven't figured that part out. Guessing we'd need to tap into Gumshoe's event API somehow.

[edemaine]

@mmistakes Ah, that is unfortunate. It indeed seems that the Gumshoe code doesn't handle this case of headers implicitly defining sections. Surprising! I've opened an issue on the Gumshoe Github: cferdinandi/gumshoe#97

[mmistakes]

Thanks for opening the issue! I've subscribed to it and will follow along with any developments to Gumshoe.

[mmistakes]

Updated Gumshoe to 5.1.0 in #2082, which supports headers. So now the TOC correctly highlights as you scroll. If you can test it out before I merge into master that would be much appreciated.

[frankhecker]

I don't know if you were asking me or edemaine to test, but anyway: I did a bundle update and am now at "minimal-mistakes-jekyll 4.15.2 from https://github.com/mmistakes/minimal-mistakes.git (at smooth-scroll-gumshoe@28ee259)". I regenerated my staging server site at frankhecker.net and checked the footnote functionality; it appears to be working correctly, and scrolling is nice and responsive on Chrome, Firefox, and Safari.

I don't have any blog posts with a TOC, so can't test that.

[edemaine]

@mmistakes I don't see Gumshoe 5.1.0 on #2082 or https://github.com/mmistakes/minimal-mistakes/tree/smooth-scroll-gumshoe. Perhaps you didn't push, or I'm looking in the wrong place? A commit ID would also suffice.

[mmistakes]

@edemaine Ooops! My push silently failed and I never bothered to check. Should be there now 1d49235

Thanks for testing @frankhecker!

[edemaine]

Thanks! I just did a quick test of my (very long) single-page site (local build -- public version hasn't been updated), and here's my impression:

• Long-distance scrolling is slow and stuttery (on Chrome on Windows). Clicking on a distanct TOC item took 10+ seconds to scroll. It seems there's a limit to speed, but I'd rather have a limit on time (0.5 seconds?) like we used to have.
• Scrolling to a new section no longer changes the URL to refer to the current section. Is this intentional? It's a change from previous behavior. On the other hand, clicking on a TOC link does change the URL, which is a nice improvement from old versions.

[mmistakes]

@edemaine Thanks for testing.

I believe there's some easing going on with the speed of the scroll. I went with the default of 300ms but apparently you can adjust that.

And re: the URL bar hash no longer changing on scroll. As far as I know the new Smooth Scroll script doesn't have that feature. I'm not so concerned about losing that. In fact the old way kind of bothered me with how it added /# when you scrolled to the top.

If there's an easy way to get the URL bar hash to change on scroll, and not add /# when you hit the top I'd be cool with that. Otherwise I think we can drop the feature.

[edemaine]

@mmistakes Thanks for the link. As I guessed, the speed setting is by default an amount of time to scroll 1000px. My document is around 40,000px, so it can take 12 seconds to scroll.

If we add the speedAsDuration: true option, though, then speed should be the total time for an animation. The default for jquery-smooth-scroll is 400ms, so to leave things as they were, we could use the following settings:

speed: 400ms
speedAsDuration: true

Alternatively, we can set durationMax: 500 or something like that. Then short scrolls will be faster, but long scrolls won't be too long.

I tried this on my local copy, and both approaches work: my scrolls are no longer several seconds. Unfortunately, I'm still getting a very jerky motion: I only get a couple of screen refreshes per second.

[edemaine]

I just tried disabling Gumshoe, and the scroll is nice and smooth again. In the code I wrote, I disabled Gumshoe during smooth scrolls, exactly for performance. Maybe we'll need to do this manually again.

The problem seems to be that Gumshoe's scrollHandler uses window.requestAnimationFrame instead of debounce, which means that it is running on every frame of the scroll animation, instead of realizing that scrolling is still happening and waiting for that to stop.

[edemaine]

I tried to reproduce the problem outside this theme, but it doesn't seem to happen with just Gumshoe + SmoothScroll. A performance analysis with Chrome suggests that it's entirely caused by FontAwesome's data-search-pseudo-elements feature. Do you use that in this theme? If not, I think removing it would remove the bad performance I'm seeing.

[mmistakes]

@edemaine I'm cool with changing the speed to more closely match jquery-smooth-scroll defaults.

Are you able to push commits to my pull request #2082 and add your code that disables Gumshoe during smooth scrolls?

[mmistakes]

@edemaine I don't personally use that feature of FA, but someone recently asked for it. I only added it because it didn't seem to have any adverse impact on performance.

Might have to reconsider that one as I don't think majority of the theme's users care or use FA icons as pseudo elements.

[mmistakes]

@edemaine I removed that attribute from the FA script and things look better on my end too. Think I'll leave it out. It's easy enough to override the theme's _includes/script.html file if someone really needs to add it back.

As far as I'm concerned it's an edge case and I'd rather improve performance for the majority of users who are using the theme unmodified.

Thanks for debugging this one for me!

[edemaine]

Cool, thanks! I just tested b9c0461 and it looks good to me!

[carlesfernandez]

Here you have another online example with the smooth-scroll-gumshoe branch (at b9c0461) with TOC and footnotes: https://gnss-sdr.org/docs/tutorials/gnss-signals

From what I tested (those features are widely used in that website), it works great.

Some slight adjustment for the scroll speed. Repo at https://github.com/gnss-sdr/geniuss-place