Outline / Table of contents improvements

[mejo-]

Describe the bug There's many issues and complaints about how the outline / table of contents feature currently works:

• The feature is hard to discover: #6876
• On small screen, it overflows the text content and is barley readable: #7522, nextcloud/collectives#1715, nextcloud/collectives#667
• We currently use display: grid for the Text editor .content-wrapper container and its left and right siblings just to have a container for the outline. This leads to all kinds of problems with printing the document (see #7553) and full width view of documents that contain a table (#7228).

Expected behavior It should be easy to toggle the table of contents. We should have a good design concept of where and how to display it, both on wide screens with much whitespace left and right to the editor, and on narrow screens without any extra horizontal whitespace.

Screenshots

See linked issues.

Cc @marcoambrosini @nextcloud/designers

[marcoambrosini]

I think we should replace all the content in the navigation with the table of contents, and add a [back] button at the top to go back to the collective navigation.

Reasoning:

• It's a navigation, we're just diving one level deeper with the page structure, so it will feel natural for users if we place this where we have navigation throughout Nextcloud
• The navigation component already comes with all the mobile goodness, it won't weirdly overlap, it closes when a router link is clicked and displays (in this case scrolls) the content

[mejo-]

I think we should replace all the content in the navigation with the table of contents, and add a [back] button at the top to go back to the collective navigation.

My main concern with this is that it breaks with the order of hierarchies from left to right. At the moment we have four panes from left to right: collective list, page list, page content, page sidebar.

I don't have a better idea though and given that it would solve quite a few issues as you mentioned, I'm not opposed to your suggestion @marcoambrosini.

Another option would be to replace the page sidebar content with it, but that would mean that you cannot access table of contents and e.g. attachments list at the same time, which is not so nice from UX perspective.

@marcoambrosini could you do rough mockups for desktop and mobile to get a better idea of how this will look like in practice?

[marcoambrosini]

@mejo- more or less like this, and this component would behave exactly like the normal navigation, so on mobile it's just as it is now with the collectives pages navigation: full screen, and collapse after tapping

https://github.com/user-attachments/assets/484996f3-0606-448b-ba06-356081b5610d

[kra-mo]

@marcoambrosini you really need that tertiary style for that back button there!

[marcoambrosini]

yeah I forgot to update the lib and change that :)

[mejo-]

Thanks a lot for the mockup @marcoambrosini. It was indeed helpful. While watching it, another issue with this approach came to my mind:

At the moment, the outline status is persistent across page reloads, i.e. when toggling the outline for one page, it will stay open for this page until you manually close it. This was a feature request with many upvotes and in Text, where it's not sticky yet, the feature request is also one of the most upvoted ones.

I guess that's impossible with the suggested solution, as it would make it impossible to navigate to other pages while the outline is open.

What do you think about this, and do you maybe have other ideas where to place the outline @marcoambrosini @kra-mo?

I guess for mobile it's pretty clear: the outline will take full page width and it's visibility will not be sticky/persisted. On desktop though we still have to take into consideration different screen sizes and the possibility of full-width view of the page.

[mejo-]

One suggestion that came in the Text issue:

How about enabling the outline by default if the screen is wide enough? It should satisfy all who need/use it and should not harm others.

[marcoambrosini]

An alternative could be to add the ability to insert the outline into the document, just as we insert a table. Right now it will be stuck as a block inline, but in the future when we hopefully have layouts, it could be dragged and moved into a column and resized.

This is how Notion approaches it:

https://github.com/user-attachments/assets/56cfdfb4-7147-40b2-8f98-14e3cc71348d

The disadvantage of this is that it's not possible at the moment to make the table of contents sticky

edit: I would skip this solution in favor of one of the following two proposals

[marcoambrosini]

How about enabling the outline by default if the screen is wide enough? It should satisfy all who need/use it and should not harm others.

I do not like this idea because many people may not need it at all and might find it distracting

[marcoambrosini]

And another possible solution, which is my preferred one at this point, would be to replace the content of NcSidebar with it.

I think we're needlessly anchored to the idea that whenever the sidebar unfolds because of a certain action triggered within the content, we have to automatically present all other possible actions that one can do in the sidebar. I don't think it makes much sense. This seems like a good opportunity for breaking out of this pattern

[marcoambrosini]

If you think it's too much to break out of the pattern at this point, I suggest we move sharing into a dialog and replace that tab with the outline. Reasoning: there's no need to be looking the document while creating a share. On the other hand when navigating an outline we have very much the need of looking at the document simultaneously

[mejo-]

In general I really like the approach to move the outline to the sidebar, both for standalone Text (opened from Files app) and for Collectives. It solves many problems at a time:

• The space for the sidebar is already taken into account in our design and we have a concept of how it works with different screen sizes.
• It provides a unified solution people can get used to both in standalone Text and Collectives.
• In Collectives we then have a clear order from generic to specific from left to right (Collectives list, page list, page content, page details).
• We can get rid of the grid container in Text app that currently provides the wrapper containers that hold the outline. The grid container currently brings many problems, with print view, with tables that overflow the horizontal editor width.

I would prefer to implement the outline as a new tab in the sidebar though, as this is technically easier and doesn't bring the problem of hiding other content in the sidebar. In Collectives I don't see a big problem with it as we currently have four sidebar tabs. In Files app (on our company instance) we already have five tabs in the sidebar. In my opinion it still works well.

[marcoambrosini]

Fine by me as well, it's undoubtedly a step in the right direction even with this not ideal amount of tabs.

Would still prefer to move sharing to a dialog though.

[juliusknorr]

Works well in English but translations will likely be cut off in a lot of languages already. However I agree that this is the most sensible position also considering the other technical factors. I remember lengthy discussions in the past about that we have too many tabs with 4/5 tabs already, so I'd like to get also some feedback from @jancborchardt here as well.

[mejo-]

Would still prefer to move sharing to a dialog though.

I tend to agree, but out of scope for Text. Something that would need to happen in the files_sharing app.

[mejo-]

After discussing this with @jancborchardt, we came up with the idea to implement the outline similar to how notion does it with some adjustments. I'll try to write down the approach:

• [x] If document has two or more headings, display outline skeleton on the right side
• [x] Extend to a popover that shows the full outline
• [x] On narrow desktop view, make the outline popover overflow the document
• [x] In outline popover, allow to pin it (make it persistent, don't collapse on mouseleave)
• [x] Don't display outline skeleton on mobile
• [x] On mobile, popover to show outline becomes fullscreen and no option to pin it
• [x] Hide and don't allow to display outline in rich workspace
• [x] Hide outline in print view
• [x] Ellipsize long headings in outline popover

Implementation details:

• [x] Get rid of grid container
• [x] Use a column on the right side with 250-300px for the outline
• [ ] In Collectives, make sure that we have enough space for drag handler and outline in the wrapping container

Outline in Notion

[jancborchardt]

@mejo- sounds good to me!

[mejo-]

Given that we also want to display an outline on mobile, how and where should it be positioned? Taking away horizontal space for it doesn't look great in my opinion:

Outline on mobile

@marcoambrosini @jancborchardt

[mejo-]

Fixed with #8033.