Is there a way to autoscroll the toc from the content in HTML

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

Is there a way to autoscroll the toc from the content in HTML

Antoine Sabot-Durand
Hi,

I have a rather large document and I'd like to provide links to some sections.

To ease life of readers, I'd like to see the TOC scrolled to the matching section (from fragment id in URL), so he can see the related topics in the document and how they are related.

Is there any solution or plan to add this feature?

Thanks
Reply | Threaded
Open this post in threaded view
|

Re: Is there a way to autoscroll the toc from the content in HTML

mojavelinux
Administrator
Antoine,

This feature is certainly achievable and something I agree would make navigating large documents much easier.

Implementing this feature involves adding some JavaScript to the page. You can add the necessary JavaScript right now using a docinfo file (or docinfo extension). This is particularly feasible since all the sections have IDs by default and the entries in the TOC refer to those IDs. The only thing left to do is coordinate the scroll position to one of the entries by toggling a CSS class.

The common name for this feature is "scroll spy". There are numerous libraries available that implement it. The one from Foundation is called Magellen {1}. If we decided to integrate this feature into core, we'll probably write something custom.

I think the next step is to implement a prototype which we can put into the extensions lab (as a docinfo extension). We can refine it there, then sort out the best way to integrate it into core, if we decide it should go there.

Here are a couple of examples for reference:


If anyone has other reference examples, I encourage you to post them.

-Dan


On Wed, Mar 16, 2016 at 3:06 AM, Antoine Sabot-Durand [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Hi,

I have a rather large document and I'd like to provide links to some sections.

To ease life of readers, I'd like to see the TOC scrolled to the matching section (from fragment id in URL), so he can see the related topics in the document and how they are related.

Is there any solution or plan to add this feature?

Thanks


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Is-there-a-way-to-autoscroll-the-toc-from-the-content-in-HTML-tp4525.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen
Reply | Threaded
Open this post in threaded view
|

Re: Is there a way to autoscroll the toc from the content in HTML

pmorch
Hi,

I needed this too and this works. It actually does two things:

* It highlights the "current" chapter / heading in the TOC with gumshoe.

* A listener to a gumshoe event causes the TOC to scroll, so the current entry is at the middle of the TOC height-wise. That works for us.

What is missing is if a user starts the page at file.html#_some_section, then the TOC is only updated when the user starts navigating. Perhaps if I fix that too, I'll update below.

I put this in my file.adoc:

:docinfo: shared-head

and put this in docinfo.html:

<script src="https://code.jquery.com/jquery-3.4.1.min.js"></script>
<script src="https://cdn.jsdelivr.net/gh/cferdinandi/gumshoe@5/dist/gumshoe.polyfills.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery-scrollTo/2.1.2/jquery.scrollTo.js"></script>
<script>
    jQuery(function () {
        var scrollspy = new Gumshoe('#toc li > a', {
            nested: false
        });
        document.addEventListener('gumshoeActivate', function (event) {
                jQuery('#toc')
                    .stop()
                    .scrollTo(event.detail.link, 500, {
                        offset: {
                            top:  0 - jQuery('#toc').height() / 2,
                            left: 0,
                        }
                    });
        }, false);
    });
</script>

<style>
    #toc li.active > a {
        font-weight: bold;
        text-decoration: underline;
        font-style: italic;
    }

    #toc li a {
        display: inline-block;
    }
</style>
Reply | Threaded
Open this post in threaded view
|

Re: Is there a way to autoscroll the toc from the content in HTML

pmorch
I wrote
What is missing is if a user starts the page at file.html#_some_section, then the TOC is only updated when the user starts navigating. Perhaps if I fix that too, I'll update below.
I was a little fast there. It does actually work out-of-the-box. I just assumed it didn't work because I didn't do anything to make it work. But gumshoe is apparently smart enough that it just works... :-)