I'm excited to pitch a new feature to Swift-DocC-Render, which I refer to as OnThisPage navigation. This is a new right sidebar component, that would visualise the current page's content headings and sections, as well as track where you are on the page, as you scroll.
The new element will be visible only for larger screens, where the content width is at least 1270px, so it does not take up valuable content space. This ensures there is enough space for the content and the sidebar on the right. This also works in tandem with the new adjustable sidebar navigator, so if you expand the navigator too much, the new sidebar will hide itself.
You can see a deployed preview here
DocC-Render PR - here
Looks great, @dhristov! In the same way we're showing h3s in the On This Page component, have you also considered showing topic group titles from Topics sections and See Also sections?
I thought about it, but I think those do not have anchors generated by docc, plus I thought it might start to look pretty busy in the nav. We can for sure add them, up to us to decide.
Maybe topic groups shouldn’t be clickable links in the right sidebar (with associated styling to show that)? They could act just a marker to remind the user of the curation of the topics in the right sidebar. I think they would be great context clues for topic links in this new sidebar.
Looks great! Thanks for your work on this @dhristov. Happy to see this feature coming back to Swift-DocC-Render in a new and improved way.
@dhristov How did you decide on this particular content width value? I noticed I can't get the "on this page" to appear on my 13inch MacBook Air which seems like it ought to be large enough for this.
I agree with @dhristov on this- the Topics are also already visible in the navigation sidebar on the left so duplicating them on the right seems pretty redundant.
@dhristov On the "looking pretty busy" topic, did you consider only enabling the "On this Page" when a page really needs it? I.e it has more than one or two headings or the subsections are sufficiently large to be moved off of one screen?
I've noticed with similar UI elements on other documentation engines that it ends up looking a little out-of-place for pages with only a single heading.
Here for example, I'm not sure the "Declaration" ever needs an entry in the breadcrumbs. And then the "Topics" and "See Also" are autogenerated so they'll appear on nearly every page which also seems a little redundant.
I think my preference would be to only use the "on the page" for items that are part of the prose/body content, not the autogenerated links or declaration sections. And then ideally "on this page" would only be activated if that body content was sufficiently large enough to actually benefit from the extra navigation.
I'm a bit curious if there's room for "on this page" elements in the sidebar. It'd help smaller viewports and might make sense for longer form content, like showing sections of a chapter. If you can link to headings from the "on this page" elements, it'd be nice if there was a way to do the same from a phone, for example.
At first glance yes, but if you look at the gutters and free space you will see there is barely room (green are gutter spaces, orange is free space). We would have to interfere with the gutter space, which generally we avoid.
That sounds pretty good, but detecting the "size" of a section might be too complex, as the size varies allot. (Images are async downloaded, space changes as you resize etc).
We can however have some checks, whether we have collected only auto generated headings (Declaration, See Also etc) or we also have some content headings in there as well, and decide whether the OnThisPage is even useful or not.
Do you mean to move the OnThisPage to the left, where the Tree navigator is? I think those are different UI elements and should probably stay separate As for whether it makes sense to have it on mobile or not, I dont think there is enough space to show it in a meaningful way anywhere
It's no biggie, of course, but the tiny glitch can be a little distracting. I guess this could be easily avoided by just coloring the active section black without the extra boldness or using a small arrow indicator.
Really nice! The right-hand side looks a bit empty right now, so I'm glad this is coming back with improvements.
One thing though - when scrolling down a page, the box feels like it sits too close to the top of the page. I think it could do with some extra spacing between this content and the navigation bar.
This looks great! Thanks for building this @dhristov
As far as I could tell, the OnThisPage navigator only shows the autogenerated h2 headers, have you considered adding a deeper level that shows heading level 3 and Topics and See Also group titles? I've seen similar UIs that add indentation to distinguish between sections and subsections.
I find this very useful in articles, but it might be a little redundant for symbol pages, IMO most of them would not need this navigator because the content will not be that big unless they have extra content added via extension files. Not sure if it's currently possible from the docc-render level since all the content for each symbol ends up in a single file, but if there's a way to tell if the symbol had additional content added via an extension, we could use that information to decide if is useful to render the file navigator.
It shows H2 and H3 from the content, as well as the main topics after the content. Subtopics are still in debate whether it makes sense to show them, since they are already in the Navigator.
Indentation is not a bad idea, but we have very little space to work with in the first place. I will have to discuss with the Design team.
In the latest PR, we added a minimum of 2 items in order to show the OnThisPage, which should help situations as the ones you described.
As for whether it makes sense to have it on mobile or not, I dont think there is enough space to show it in a meaningful way anywhere 
