New Feature: Navigation indication on the right TOC

[quickstar]

Hi

I think it would make sense to have a visual indication on which chapter on page the reader currently is.

The Airflow example has a nice implementation to showcase this feature.

As one can see the chapter which the reader has scrolled to, is visually highlighted on the right.

I think such a feature would greatly enhance the usability of docsy in general. What do you think?

---

Proposals

• Build the right-side table of contents from javascript - updated version #2273
• Add support for BS ScrollSpy to show active TOC entry #2287

[LisaFC]

Oh that is nice, especially for long pages. I like that the highlight automatically scrolls up and down as you scroll up and down the page. Anyone with the skills to implement this, please jump in (or chime in if you don't think it's useful).

[prdsoftware]

+1 from me. That's slick. This kind of feedback not only helps the reader understand where they're at, but also encourages exploration further down the page. Would love to see this in Docsy one day.

[Symbolics]

Just wondering, as someone who doesn't know a great deal about the web tech: if Airflow, which is based on Docsy has this, what stands in the way of back-porting it to Docsy? I think this adds a bit of user friendliness.

[shuuji3]

Hi, @Symbolics.🙂 Unfortunately, though the style of the Airflow documentation is similar to the Docsy, it seems that Airflow documentation itself uses Sphinx (ref. airflow/docs at master · apache/airflow) instead of Docsy. Sphinx is yet another documentation tool written by Python so we cannot simply back-port it.

But I think your idea has a good point. if there is a Docsy website that has already implemented the side navigation somewhere, we could back-port it.

[Symbolics]

I see. I was confused because Airflow is listed as a customised Docsy example on the examples page. Perhaps it should be removed there, or a note added about it using both Docsy and Sphinx.

[Symbolics]

As a general note, I think the impact that visual elements have on reader experience should not be underestimated. Even hard-core techo's know that it's about functionality, yet are still subconsciously affect by the way the pages look, and this affects overall project uptake.

[shuuji3]

@Symbolics I'm sorry, I was wrong. The airflow documentation repository in the "example page" you pointed out uses Docsy certainly. I only saw another repository which is the source of the documentation of that repository.

After I investigated the repository, I found the implementation of this feature: https://github.com/apache/airflow-site/blob/master/landing-pages/src/js/progressTracking.js. To summarize, when users scroll a page, it calculates the current position and adds a "current" class to one of the sections to indicate the current place.

As a general note, I think the impact that visual elements have on reader experience should not be underestimated.

I agree. From my experience, I spend a lot of time reading documentation using the Docsy theme but sometimes lose my way because there is no indication of where I'm reading on the sidebar. Giving the context to users should improve the understandability of users.

[LisaFC]

Thanks @shuuji3 for taking the time to find the JS that the Airflow site is using for this feature! If I have time I'll see what would be involved in adding something similar to our right nav - or if anyone with more experience would like to have a go?

And yes, I agree that visual elements are important! I am a tech writer rather than a web designer and our first iteration was very focused on structure and getting the basic navigation setup (while not looking terrible!), I'd love to add more useful visual cues to the template.

[shuuji3]

Thank you @LisaFC, I have a strong motivation for realizing this feature so I'd like to try to implement it! As a first step, as @quickstar suggested and I already investigated, I'll try to back-port the script used by the Airflow documentation and amend it for the default Docsy template. Is there any suggestion?

One question: if we add a new JavaScript file, which is the right place to put it: https://github.com/google/docsy/tree/master/assets/js or https://github.com/google/docsy/tree/master/static?

[LisaFC]

Oh that's great! Either directory will work (though I think with assets/ you can do more things to the JS, eg minify, as the files in assets/ can be processed further).

[shuuji3]

Thanks for your advice! I'll try to implement it.

[quickstar]

Hi @shuuji3
Pretty cool to see someone is investigating on this topic! Good luck, let me now if I can assist in any way.

[shuuji3]

Thanks @quickstar ! I'd like to ask your help if I stuck somewhere.🙂 Also, thanks for your starting out this issue.