Emitting a custom event for anchor tracking

[heitorlessa]

Contribution guidelines

• I've read the contribution guidelines and wholeheartedly agree

I want to suggest an idea and checked that ...

• ... to my best knowledge, my idea wouldn't break something for other users
• ... the documentation does not mention anything about my idea
• ... there are no open or closed issues that are related to my idea

Description

I'm enabling Anchor Tracking as part of the migration to MKdocs Material 8.x. This feature can help give a more accurate analytics on which sections are more popular than other - however, I've just noticed it's rewriting the history state.

With my limited research on history rewriting, I can't hook up to any event (e.g. popState) to send a custom anonymous page view for that section being tracked.

Would you consider creating a custom event so we can use this great feature for analytics purpose too?

Thank you as always for this great theme!!

Use Cases

Use the new anchor tracking feature to send more accurate page view for sections being scrolled to.

Screenshots / Mockups

No response

[squidfunk]

Moving to discussion, since this is a customization request. It's definitely possible to achieve, as the whole architecture is based on observables. In essence, you can observe the table of contents element and check which is the active section.

[heitorlessa]

As I'm new to this, would you be able to share a rough example or someplace I can read more about how I can achieve this?

Happy to even contribute a FAQ if you think it's useful

[squidfunk]

#3429 (comment) provides some notes on the general extensibility mechanism and an example to detect color palette switches, which is similar. I'm afraid I can't hack something together for your purpose as I'm really short on time right now, but my comment should yield some insight on how the theme exposes component events. component$ is the observable you're looking for, and within that you need to filter for the table of contents component. Maybe someone else can cobble something up.

[heitorlessa]

#3429 (comment) provides some notes on the general extensibility mechanism and an example to detect color palette switches, which is similar. I'm afraid I can't hack something together for your purpose as I'm really short on time right now, but my comment should yield some insight on how the theme exposes component events. component$ is the observable you're looking for, and within that you need to filter for the table of contents component. Maybe someone else can cobble something up.

That's great - I can figure it out from there. Challenge was more whether it was possible, and if so where to start hacking a solution for it. I wouldn't ask for a ready-to-use solution from you - I'm also a maintainer elsewhere, I know the drill ;)

Thank you so much again

[squidfunk]

Awesome 😊 Feel free to share it when you figure it out!

[heitorlessa]

That helps already ;-) I know where to start now - thank you!

…

On Fri, 4 Feb 2022 at 17:54, Martin Donath ***@***.***> wrote: #3429 (comment) <#3429 (comment)> provides some notes on the general extensibility mechanism and an example to detect color palette switches, which is similar. I'm afraid I can't hack something together for your purpose as I'm really short on time right now, but my comment should yield some insight on how the theme exposes component events. component$ is the observable you're looking for, and within that you need to filter for the table of contents component. Maybe someone else can cobble something up. — Reply to this email directly, view it on GitHub <#3538 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAZPQBFS2O4BIB26RR3FCDDUZQAGBANCNFSM5NSH4HIQ> . You are receiving this because you authored the thread.Message ID: ***@***.*** com>

[heitorlessa]

Sure thing! I need to learn RxJs first and its operators, then revisit source code to see what’s being exported besides “location$, viewport$”. I noticed things like takeUntil and denounce from RxJs aren’t exported - so just need some trial and error until I figure it out ;-)

…

On Fri, 4 Feb 2022 at 18:20, Martin Donath ***@***.***> wrote: Awesome 😊 Feel free to share it when you figure it out! — Reply to this email directly, view it on GitHub <#3538 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAZPQBCFKTHGQHE76YLIQ2LUZQDFXANCNFSM5NSH4HIQ> . You are receiving this because you authored the thread.Message ID: ***@***.*** com>

[squidfunk]

Yeah, all used operators are bundled. I thought about exporting them, but then I figured that 99.9% of users won't need them anyway, as RxJS is a pretty tough end boss to beat, so I discontinued that idea. Maybe I revisit it in the future, but I'm not sure I want to burden myself with an increased need for support for users trying to make their RxJS pipelines work. It's a quite bumpy ride 😉

[heitorlessa]

Nah I’d say don’t - it’s not the core premise, and as you pointed out it’ll highly likely become RxJs support from the little I just read from their docs. I find events easier to decouple on that front, it’s agnostic. Maybe documenting and emitting a set of events people can listen to with plain JS, so they can extend as they please (search, anchor tracking, etc) — that can open up a more flexible customisation without burdening you I’ll look up the codebase to learn more about the anchor tracking came together and use as a basis.

…

On Fri, 4 Feb 2022 at 19:04, Martin Donath ***@***.***> wrote: Yeah, all used operators are bundled. I thought about exporting them, but then I figured that 99.9% of users won't need them anyway, as RxJS is a pretty tough end boss to beat, so I discontinued that idea. Maybe I revisit it in the future, but I'm not sure I want to burden myself with an increased need for support for users trying to make their RxJS pipelines work. It's a quite bumpy ride 😉 — Reply to this email directly, view it on GitHub <#3538 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAZPQBARJLRPRURGFN6YQEDUZQIJ7ANCNFSM5NSH4HIQ> . You are receiving this because you authored the thread.Message ID: ***@***.*** com>

[squidfunk]

You can listen to all RxJS events with plain JS by using .subscribe(). Also, where to start? Which events to emit? All of them? There are many, so it would be more to maintain. Thus, I'd rather leave it low-level via .subscribe() for those who want to customize and rather emit the raw stream of events to filter from. Also, the docs contain some examples.

You can probably imagine that maintaining an HTML template is a lot of work. It's super opinionated and basically, everyone wants to get his way 😉 I've been doing that for 6 years now and my experience tells me that striving for maximum flexibility is the best approach to keep the cost of maintenance reasonable.

[heitorlessa]

I certainly missed that from the docs, hence the ask for not knowing where to start. I'll look up on Sunday.

Thanks a lot

[heitorlessa]

location$.subscribe is under custom analytics section, which I clearly missed because I used that on 6.x only (changed on 7.x for RxJs from Webpack).

https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-analytics/

My initial attempt at using location$ didn't work because I wasn't using instant loading which all makes sense now.

[heitorlessa]

Found a solution using monkeypatching (not great, not terrible; gets the job done).

var replaceState = history.replaceState;
history.replaceState = function () {
    const url = location.href
    var section = url.split("#")[1]
    if (section != undefined) {
        console.log(`TOC section changed: ${section}, url: ${url}`)
    }
    replaceState.apply(history, arguments);
};

Lessons learned from this experiment in case it's helpful to anyone else:

• history.replaceState doesn't trigger a popstate event in the browser. Anchor tracking feature uses history.replaceState to seamlessly rewrite current history so the browser doesn't have to do additional checks whether the URL exists; downside is not having an event to act upon like the analytics use case I had.
• mkdocs-material exports key RxJs Subject objects to ease customization. For this use case, location$ doesn't help us as history.replaceState is being called, so there is nothing to be observed. You could however use viewport$ and try filter events on every scroll but at this point you're a) rewriting anchor tracking feature, and b) doesn't have access to RxJs from global namespace to use operators like pipe and filters like debounceTime to sift through what matters (I'm a JS newbie so maybe there is a way).
• mkdocs-material documentation does mention about RxJs. I missed the part of the documentation that RxJs is used to ease observing changes. The only piece missing is what components are exported, and their potential use customization use cases - this block shows all exports) that can cover the majority of the use cases.
• communicate with care. Looking through my responses on a Friday night by my phone I realized I could have framed things better -- questions over comments: e.g., have you considered X? vs I'd suggest X. Words can be terse and can hardly express one's state of mind. Typing on laptop, revising twice before sending, or more importantly not doing it on a Friday night (;)) is what I'd exercise more to come across better next time.

If you think this could be useful to someone under Custom Analytics or any FAQ section, I'm more than happy to make a PR to document this.

Thanks for the pointers @squidfunk !