Add table of content for a specific page on the right side

[logankilpatrick]

I have been reading through: https://code.visualstudio.com/docs and absolutely love that the right side shows a highlight of the page. I feel like it would be pretty straightforward and helpful to pick up on the headers from the page and show them on the top right, especially since the space is not utilized anyway.

[mortenpi]

For future reference: there is discussion about this in #1563, including a simple mockup of the TOC.

[rmNULL]

@logankilpatrick Hi,
I went through the other thread(#1563), having a TOC on the right can solve the problem i face.

However i would like it to include all possible links.
For e.g:
Say i visit Base/Filesystem
The TOC should somewhat resemble

• Base.Filesystem.pwd
• Base.Filesystem.cd
• Base.Filesystem.readdir
• Base.Filesystem.walkdir
  ....
  It would be helpful to know if i should start working on this or shall we agree on a design and then start the implementation.

P.S: i need some time to go through the implementation on how the documenter works.

[mortenpi]

Hmm, I was glancing at #1715 and I noticed that this actually duplicates what we already have. The current TOC shows the h2 headings of the current page, and the sidebar jumps to that part of the sidebar on page load and should therefore generally be visible to the user. I guess the question is whether that is good enough UX for this or not.

[logankilpatrick]

Yeah, I am not sure, it just seems like wasted valuable space right now

[rmNULL]

Hi,
I agree there are h2 headings in the current implementation, however those headings are not complete listings.
For e.g: the left TOC shows Base > filesystem but it doesn't list all the children of Base.FileSystem,
Which makes it harder to get an easy overview of the list of all available functions.
(You can find the original intention behind the PR discussed at julia lang).

iirc originally i had thought of 3 ways of solving this,

1. updating the existing TOC to accommodate the change.
2. having a separate right TOC.
3. All the cards in the page open with a folded view.

And since we were discussing about having a right TOC,
that was picked for the #1715 implementation.
i took the right TOC to mean "overview of the currently viewing page",
and the left TOC be an overall site navigation.

If need be, we can implement this in left TOC,
as both of them address the primary issue.
And like you pointed out, which one is good UX, i'm not sure,
although i'm biased towards having a separate TOC on the right for the desktop view.

P.S: I'm not sure if that answers the questions you were addressing.

[mortenpi]

I don't think we want add more stuff into the left sidebar, so if we're going to have additional information there, then I think it should go on the right. It is also an option to consider removing the h2 headings from the left sidebar altogether, if we're going to have them on the right. One would need to make sure that the two sidebars also work well on mobile too though.

I think right now the main thing is to clearly decide what exactly should go into the sidebar on the right. Regarding the Base > Filesystem example: we currently distinguish between the headings on a page (at-contents block) and the docstrings on a page (at-index block). Since we already have those blocks though, should we think of the right sidebar to essentially be a out-of-page version of one of those, or even a combination of those?

[rmNULL]

I don't think we want add more stuff into the left sidebar, so if we're going to have additional information there, then I think it should go on the right. It is also an option to consider removing the h2 headings from the left sidebar altogether, if we're going to have them on the right.

I think right now the main thing is to clearly decide what exactly should go into the sidebar on the right.

Second this.
Having a clear idea about this should also resolve the h2 issue.

i recall this being a problem while implementing the right TOC,
along with other things like same kind of tag showing up multiple times(
they shared the same name but different function signatures).
its an error on my part that i didn't write down these problems while i faced them
and now my memory has completely failed me.
i'll go through the source later and get back in a day with more details(hopefully).
If you already have something in your mind on how things should be organized that would be helpful(
and save some energy on my end :)

One would need to make sure that the two sidebars also work well on mobile too though.

getting it to work on mobile would require some redesigning but once we have the organization part
figured out, im hopeful that we can figure out what information to retain and the right place to show them.

Since we already have those blocks though, should we think of the right sidebar to essentially be a out-of-page version of one of those, or even a combination of those?

i'm not sure i follow.

[mortenpi]

Since we already have those blocks though, should we think of the right sidebar to essentially be a out-of-page version of one of those, or even a combination of those?

i'm not sure i follow.

What I meant is that since we have the two at-blocks (@index for docstrings and @contents for heading ToCs) that generate in-page ToCs, should the right sidebar perhaps just emulate those, except only that it ends up out of page on the side? The question is whether the sidebar should contain the information in the at-contents block, in the at-index blocks, or mix the information from both?

[inkydragon]

whether the sidebar should contain the information in the at-contents block, in the at-index blocks, or mix the information from both?

The first version uses the contents of @contents by default.
Later, we may consider allowing users to mix @contents and @index through an option.
Or we could learn from ruby's document style and distinguish between TOC and @index.

https://docs.ruby-lang.org/en/3.2/IO.html

---

The style of the python devguide documentation looks good.
https://devguide.python.org/getting-started/setup-building/

[mortenpi]

Or we could learn from ruby's document style and distinguish between TOC and @index.

Separating them seems like a good idea, either by having them one after another, or maybe as two tabs of the right sidebar.

But also, yes, for an MVP, I think it's fine to focus on just at-contents.