DocC renderer incompatible with :~:text= fragments

[gwynne]

Description

In the present day, all of the major browsers have support for what MDN refers to as text fragments, which allow linking to any location on a given page - regardless of whether that location has an associated <a name=""> element - by specifying particular text on that page.

The short of it is, text fragments don't work in DocC catalogs. This is presumably related to the implementation of src/mixins/onPageLoadScrollToFragment.js.

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Expected Behavior

Navigating to a link pointing to DocC documentation which includes a text fragment should scroll to the first occurrence of that text on the page in question.

Actual behavior

The top of the page is displayed. If using Safari, the URL in the address bar is reset to have an empty fragment (e.g., just #).

Steps To Reproduce

1. Using any recent version of Safari, navigate to https://docs.swift.org/swift-book/documentation/the-swift-programming-language/attributes#:~:text=buildPartialBlock.

Swift-DocC-Render Version Information

b6cf582

[mportiz08]

Interestingly, I've seen it work sometimes but most of the time it doesn't.

I think you're right that it's likely a bug with some of our logic for handling fragment links/scrolling. Given the fact that it does sometime work, I'm guessing there's some sort of race condition or bad async code. 😢

\cc @dobromir-hristov

[dobromir-hristov]

OK here are my findings, from lots of digging and testing around

1. The routing library VueRouter is not necessarily preventing this from working, but it does strip it out the fragments from the URL, upon page load. In order to init some state in the current page, the router calls history.replaceState, which rewrites the current url entry. This is not something we can control, and is crucial to the way the router works.

This also happens, because none of the browsers include the fragment (#:~:text=foo) in window.location.hash. This means we cannot even read it, nor can vue router to interact with it. We cannot replicate the functionality on our end either.

2. Since page content is async fetched from an API, the speed at which it’s rendered is highly variable. The browser tries to do the highlighting and scrolling in the first ~200ms of the page load. After that the page is rendered as is. I noticed static elements like the left sidebar are sometimes highlighted, but the content almost never.

Unfortunately there is no way to tell the browser to await, until you say the page is ready.

On an new fresh install of Vue, with content that is pre-bundled (meaning it is not fetched from API) it actually does highlight. But as soon as you delay the page render by > 200ms, simulating an async fetch process, highlighting is gone.

3. When using JS to navigate to a page with a text fragment, like how we do when you use the app, the browser never highlights text fragments. This feature is apparently disabled when using JS navigation, and is only triggered from doing standard page navigation.

We cannot give authors the ability to use such links in their content, as it will work some of the times, but not all of the times.