Direct links to subsections with id don't work
vitr opened this issue · 10 comments
For example, this link https://jhildenbiddle.github.io/docsify-themeable/#/markdown?id=tables
doesn't lead to the desired section 'Tables'. The page hasn't been scrolled to the correct position, which is annoying.
The original docsify project doesn't suffer from this issue, see
https://docsify.js.org/#/write-a-plugin?id=edit-button
I think this might be an issue with the Docsify Tabs plugin which that page uses.
You can see a less dramatic similar problem on their docs page:
https://jhildenbiddle.github.io/docsify-tabs/#/?id=customization
Good catch, both on the bug (@vitr) and the cause (@jackbentley). This bug occurs because the tabs are rendered after docsify has scrolled to the URL position. This should be fixed. I'm going to transfer this issue to the docsify-tabs repo and track it from there.
Hi @jhildenbiddle,
could you please let us know some ETA
@vitr, @jackbentley, @DaveLomber --
Apologies for the slow turnaround on this.
Unfortunately, this is a docsify issue that has been discussed multiple times:
There's even a PR to fix the issue for images, but that isn't going to address the issue for plugins:
The short explanation is that docsify begins scrolling to the section specified in the URL before plugins (like docsify-tabs) or external content (image, video, AJAX content, etc.) have loaded. When plugins or external content change the content dimensions, they also change the scroll position of each section. Docsify fails to account for this, and as a result it scrolls to the original (incorrect) scroll position of the section specified in the URL.
An actual fix would involve using ResizeObserver (and MutationObserver as a fallback) to continuously monitor for content height changes, then scrolling (if the section has not already been scrolled to) or jumping (if the section was previously reached) to the section until a user-initiated scroll is detected. Monitoring for content height changes is the only way to detect all scroll position changes regardless of how or why they happen. Once a user-initiated scroll is detected, observers used to detect content changes and event listeners used to detect user-initiated scrolling can be removed so there's no left over cruft. Most importantly, this solution allows users to land on a page, have the correct section scrolled into view, and have that section remain in view even as content loads above the target section (which would normally cause the content in view to shift down).
I'll mention this fix in the PR linked above, as it handles all cases (instead of just images) and it seems easier to implement that the image-only fix proposed.
I'm going to close this bug and direct conversations to docsifyjs/docsify#723 as this really is something that needs to be fixed in docsify and not a theme (docsify-themeable) or plugin (docsify-tabs).
wow, thanks for the explanations, makes sense to me, but this is definitely not easy as I thought. I guess the technology isn't there yet, I moved back to the statically generated docs in python))
This isn't a problem unique to docsify. The same issue can happen on static HTML pages.
Imagine the following scenario:
-
You navigate to http://website.com#foo
-
On that page the markup is as follows:
<img src="image.jpg"> <p id="foo">Some text</p>
-
When the page loads, it immediately jumps to the
<p id="foo">element so that it is aligned with the top of the browser window. You begin reading and all is well. -
A few seconds later the
<img>finally loads, and it turns out that the image is 1000 pixels tall so it pushes the<p id="foo">element 1000 pixels down the page. The text you were reading just a few seconds ago is now out of view and you're left staring at an image instead--definitely not what the original URL was intended to show you.
This is exactly what's happening with docsify. It's scrolling to where the target element is initially, but that same target is pushed up/down the page as new content is inserted into the DOM. It can be fixed, but some work needs to be done. The work isn't necessarily difficult, but it also isn't a trivial fix either. I've added my suggestion to the linked docsify PR, so hopefully we'll see some progress soon enough.
is there image height attribute? like <img src="image.jpg" width=100 height=100> and even if we don't have an image, a browser shows a red cross placeholder 100x100, but I understand in a responsive layout height is something out of this world.
Specifying image dimensions will prevent the content push behavior in the scenario outlined above. In fact, recent changes in modern browsers allows the aspect ratio to be determined from the height and width attributes even in responsive scenarios. Here's an interesting link on the subject:
This makes the following perfectly valid:
<img src="image.jpg" height="300" width="400" style="width: 100%;">Three issues:
- While docsify supports image sizing in markdown, not all markdown implementations do
- Manually determining image sizes and adding dimensions in markdown/HTML is tedious
- This does not resolve the scroll position issue caused by docsify plugins
This is why I proposed the solution above--it solves all of these issues without requiring any additional work on docsify users.
Thanks @jhildenbiddle 👍