New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
New Feature: Navigation indication on the right TOC #349
Comments
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). |
+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. |
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. |
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. |
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. |
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. |
@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.
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. |
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. |
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? |
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). |
Thanks for your advice! I'll try to implement it. |
Hi @shuuji3 |
Thanks @quickstar ! I'd like to ask your help if I stuck somewhere.🙂 Also, thanks for your starting out this issue. |
@LisaFC @quickstar I've just created a draft PR to implement this feature. Sorry for the late! 🙏 Could you please take a look at it and provide some feedback? Thank you. 🙂 |
Hi all, I added this myself in a new script I created. I saved the script as scrollspy.js in a static\js folder and then I referenced it partial\hooks\bodyend.html.
And then add your css:
|
Thank you, @arnonzooz 🙂 I didn't notice the |
This update looks very nice! |
@shuuji3 I think you can replace the code, but I assume that's for @LisaFC to decide :) By the way, you might not always have a side TOC. So I added a check to prevent the scrollspy from throwing an error:
|
@arnonzooz pretty cool approach! I didn't even think about an IntersectionObserver to implement such a feature, even though it now seems pretty obvious 😅 Does this mean, the PR #506 is now obsolete? |
Hi, sorry for my slow update. I think I can update PR #506 using the above logic but it's OK to make it obsoleted and create a new PR by either me or someone else. |
Here's another nice example of this...with dynamic expand/collapse of the relevant section. https://docs.coveo.com/en/346/javascript-search-framework/javascript-search-framework-components |
Hi there, #506 is more complex, however. |
So sad this hasn't been implemented yet, what is holding us back? |
There's a PR in progress in #1049 that I think will meet everyone's requirements.... |
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?
The text was updated successfully, but these errors were encountered: