Make the top of page more easily reachable

[dvarrazzo]

The right-hand-side navigation doesn't have a way to go on top of page.

Example: https://pradyunsg.me/furo/customisation/

By using the right links, you can go at "Theme options" most. If there is a lot of content between Customisation and Theme options you cannot access that section of page via that menu.

Would you feel useful to have "Customisation" there too?

[pradyunsg]

Oooooo.

Question: would it being at the same level as the rest of the content be sufficient? Or... Maybe this should have a floating "take me to the top" button instead?

[dvarrazzo]

What I had in mind is something at the same level: the first level to be "demoted" to the second ones (the ones currently displayed). I don't think there is the need of adding one level of structure.

While "go to top" would fulfil the same need, the title is more descriptive: it would be the complete summary of the page in the right column.

Using the above link as example:

[pradyunsg]

HMM!

So, what Sphinx gives us is actually a tree that's something like:

• Customisation
  • Theme Options
    • ...
    • ...
    • ...
  • Page specific tweaks
    • ...
  • Custom CSS files

Furo actually has dedicated CSS to specifically hide the top level item and dedent the rest, since, well, that's the approach most "ToC tree in the sidebar" documentation themes seem to take. I've not seen anyone add the title of the page there, which makes me a little wary of that idea.

THAT SAID, I do agree that this is a reasonable request (being able to go to top of page).

[pradyunsg]

Yeeaaa... I'm not sure I can say that this would work well.

[pradyunsg]

Maybe a back-to-top arrow beside "contents"?

[dvarrazzo]

Why do you think doesn't work?

In my view it's perfect. It's a personal opinion, I'm aware, but I don't see what is wrong in what you have there.

[pradyunsg]

I definitely said that based on how it "felt". I guess, more words world be:

• The other headings are "under" the Image heading, and that isn't reflected by this.
• "Image" won't get highlighted by the JS that's used, because Sphinx provides # as the URL for the top-level tag, not the actual section ID. :(
• You'll see the page name in 3 places, with 2 of them being # URLs (both in sidebars), which feels like unnecessary/useless redundancy. (yes, useful redundancy is a thing)

But yea, as you say, a lot of this is personal opinion based. It might just be that I don't like any answer to the problem, even though I feel like this is a problem worth solving.

[dvarrazzo]

I know that structurally speaking is a lie. However you will have only one of those levels in the page (I know, because in psycopg3 docs I had more than one... and that menu wasn't display correctly 😛 now I change the docs to reflect the navigation possibilities in furo [1]). So it's not particularly informative to know that the first entry is the first, it's the king, and rules the others:

Smug title 🤐 It doesn't add much, does it?

About the name repeated in three places, I assume left column, title, right column, right? I think it's not bad:

• left and right column are far away. The repetition is on always under the eye.
• the title will scroll up, leaving the repetitions in the two columns apart
• the page title in the two columns tells two different things:
  • on the left, the position of that title in the whole document
  • on the right, the position of that title within the current page

So I would say that for me is informative repetition :)

[1] If you want to know what I mean you can check out psycopg/psycopg@8a71e9c

[dgw]

Putting the page title under "contents" like that last screenshot isn't just useless redundancy; it's semantically incorrect. The page doesn't contain itself.

I agree that this problem is worth solving, though. Speaking of not liking any of the answers: What about a floating button that scrolls to the top? Seems to be a fairly common pattern now.

[pradyunsg]

Speaking of not liking any of the answers: What about a floating button that scrolls to the top?

Where do you "float" that button on desktop / tablet / mobile? :P

[dgw]

Speaking of not liking any of the answers: What about a floating button that scrolls to the top?

Where do you "float" that button on desktop / tablet / mobile? :P

Same everywhere, lower right corner of the viewport, on top of everything. I'm on mobile now but can find and share some examples later if you like.

[dvarrazzo]

The right column doesn't scroll, so it wouldn't need to float :)

Still at personal "like/don't like" level, I'm not fond of floating buttons. A "Top 🔝" button in the right menu would be a first iteration to fix the problem of having a way to go back to the top of the page. But if you replace the word "top" with the first level title, that's also "a reason" to click on that label.

I don't think that "Customisation" is the title of the page. You can have documents with more than one title at the same level.

# Level 1
## Level 2
### Level 3
# Level 1 2
## Level 2 2
...

this is alloweds in Sphinx, but furo breaks it. I had to split the docs in several more pages in order to accommodate that (psycopg/psycopg@ee26c7e) which I was happy to do as furo has just a different style of navigation compared to sphinx.

[pradyunsg]

this is alloweds in Sphinx, but furo breaks it.

Well, it's also semantically wrong to have multiple h1 tags on the same page. :)

Same everywhere, lower right corner of the viewport, on top of everything.

Fair enough. In that case, this is blocked by ReadTheDocs' embedded version selector. This likely needs to wait until ReadTheDocs' support for that selector becomes better (being discussed in readthedocs/readthedocs.org#8052).

[screenshot showing the RTD version selector in the bottom right corner today]

[pradyunsg]

There's now a "Back to top" button that shows up when you scroll up while browsing the page.

Screen.Recording.2022-02-18.at.09.39.00.mov

Added in 7e0f828.

[pradyunsg]

Closing this, since I consider this resolved with the back to top button. It'll be in the next release.