Page MenuHomePhabricator

[Epic] Improve the table of contents
Closed, ResolvedPublic

Description

Background

A main goal of the Desktop Improvements project is to make frequently used tools more accessible to readers and editors. One of the most crucial of these tools is the table of contents (ToC), which is responsible for providing both contextual insight and navigation.

Currently, the ToC is only available at the top of the page, limiting its usefulness. We plan to make it a persistent element, available throughout the page. Our goal is to make it easier for readers and editors to reach the ToC, gain context, and navigate throughout the page without needing to scroll all the way to the top.

Sign off steps

When signing off please make sure

Use Cases

As a reader or editor, I want the ability to gain context (content and structure) about the page I am about to read
As a reader or editor, I want the ability to reference the next few sections in the page at any location in the page so that I can choose what to read next
As a reader or editor, I want the ability know how many sections a page has without having to scroll all the way up

Feature description and requirements

The table of contents will appear persistently on one side of the page. This table of contents will contain all sections and sub-sections available in previous versions of the ToC.

The ToC will contain the following functionality:

  • Collapsible sub-sections - for users that only want to view the highest level of section heading
  • Active section styling - the active section (i.e. the section currently in view) will be styled differently than the other sections. Users will be able to identify where on the page they are currently located.
  • Navigation - selecting a section within the table of contents will navigate to the appropriate section within the page
  • For screen widths smaller than 1000px, the ToC will collapse and the section titles will be used as a ToC
Mediawiki Page

https://www.mediawiki.org/wiki/Reading/Web/Desktop_Improvements/Features/Table_of_contents

Previous Research

Based on the research we conducted (link to research) we plan to implement a persistent table of contents on Article pages (and possibly other namespaces in the future).

Latest prototypes

Tall/collapsed ToC: https://di-article-tools-da959.web.app/Humpback_whale
Short/expanded ToC: https://di-article-tools-da959.web.app/Cetacean_surfacing_behaviour

Related Objects

StatusSubtypeAssignedTask
Resolvedovasileva
Resolvedovasileva
DeclinedNone
Resolved alexhollender_WMF
StalledJScherer-WMF
Resolvedovasileva
ResolvedJdrewniak
Resolvedovasileva
Resolved iamjessklein
Openppelberg
Resolvedovasileva
DuplicateNone
ResolvedJdlrobson
ResolvedBUG REPORT matmarex
Resolved matmarex
Resolvedcscott
Resolvedovasileva
Resolvedovasileva
Resolved alexhollender_WMF
Resolvedovasileva
ResolvedEdtadros
ResolvedJdrewniak
ResolvedBUG REPORTJdlrobson
DeclinedKrinkle
ResolvedJdlrobson
ResolvedEdtadros
Resolvedovasileva
ResolvedJdlrobson
Resolvedcjming
ResolvedJdlrobson
Resolvedovasileva
Resolvedovasileva
OpenBUG REPORTNone
ResolvedJdlrobson
ResolvedPRODUCTION ERRORJdlrobson
ResolvedBUG REPORTJdlrobson
ResolvedBUG REPORTovasileva
ResolvedJdrewniak
Resolvedovasileva
Resolvedbwang
ResolvedJdrewniak
ResolvedJdlrobson
Resolvedovasileva
ResolvedJdlrobson
ResolvedJdrewniak
Resolvedovasileva
Declinedovasileva
Resolvedovasileva
Resolvedovasileva
ResolvedEsanders
ResolvedSpikebwang
ResolvedBUG REPORTEdtadros
ResolvedJdrewniak
Resolvedovasileva
Resolvedovasileva
ResolvedEdtadros
Resolvedovasileva
ResolvedJdlrobson
Resolvedcjming
Resolvedovasileva
Resolvedovasileva
Resolvedovasileva
ResolvedEdtadros
ResolvedBUG REPORTJdlrobson
ResolvedBUG REPORT nray
ResolvedEdtadros
ResolvedBUG REPORT nray
Resolvedjwang
Declinedjwang
Resolvedjwang
Resolvedjwang
Resolvedovasileva
Resolvedjwang
ResolvedJdlrobson
ResolvedBUG REPORTovasileva
Resolvedovasileva
Resolvedovasileva
Resolvedovasileva
Declinedovasileva
ResolvedJdlrobson
Resolvedovasileva
Resolvedovasileva
Resolvedovasileva
Resolvedovasileva
ResolvedNone
Resolvedovasileva
Resolvedovasileva
ResolvedEdtadros
Resolvedovasileva
Resolvedbwang
Resolvedovasileva
ResolvedBUG REPORTABorbaWMF
ResolvedBUG REPORTovasileva
ResolvedFeatureJdlrobson
ResolvedJdlrobson
ResolvedBUG REPORTovasileva
Resolvedjwang
Resolvedovasileva
ResolvedBUG REPORTovasileva
Resolvedovasileva
ResolvedJdlrobson
Resolvedovasileva
OpenNone
ResolvedBUG REPORTovasileva
ResolvedJdlrobson
Resolvedovasileva
Resolvedovasileva
Resolved alexhollender_WMF
ResolvedNone
Resolvedovasileva
ResolvedNone
DeclinedNone
ResolvedFeatureNone
ResolvedNone
ResolvedNone

Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes
Jdlrobson updated the task description. (Show Details)

Ah, I suppose this is the place to comment. (I had posted this on T302046 but this task seems more appropriate) Feedback time!

That left-of-the-article TOC is a horrible nightmare. I absolutely hate it. I would seriously avoid any website that forced it upon me. Can't scroll it out of sight, can't collapse it, can't disable it, takes up too much space, I hate it I hate it I hate it. This was the reason I switched back to Vector classic on beta cluster. (and if Vector classic gets it too I'll switch to Monobook, Timeless or just murder it with a userscript) I'm not much of a fan of Vector 2022 (but it's not a lost cause, just needs work), but this TOC pushed me over the edge.

As a personal note: I rarely use the existing TOC. But I can scroll it out of sight so it doesn't bother me. If the TOC went completely missing tomorrow, I wouldn't miss it. Having this big, (to me) useless thing that contrasts with the main content (it's much darker) permanently in my field of vision greatly annoys me. And because of the fixed position, my banner blindness fails to kick in. This results in pure hatred for something that, on the face it, could seem innocuous.

Ah, I suppose this is the place to comment. (I had posted this on T302046 but this task seems more appropriate) Feedback time!

That left-of-the-article TOC is a horrible nightmare. I absolutely hate it. I would seriously avoid any website that forced it upon me. Can't scroll it out of sight, can't collapse it, can't disable it, takes up too much space, I hate it I hate it I hate it. This was the reason I switched back to Vector classic on beta cluster. (and if Vector classic gets it too I'll switch to Monobook, Timeless or just murder it with a userscript) I'm not much of a fan of Vector 2022 (but it's not a lost cause, just needs work), but this TOC pushed me over the edge.

As a personal note: I rarely use the existing TOC. But I can scroll it out of sight so it doesn't bother me. If the TOC went completely missing tomorrow, I wouldn't miss it. Having this big, (to me) useless thing that contrasts with the main content (it's much darker) permanently in my field of vision greatly annoys me. And because of the fixed position, my banner blindness fails to kick in. This results in pure hatred for something that, on the face it, could seem innocuous.

I don’t think Phabricator is generally the right place for this type of feedback, there is a dedicated page for it on mediawikiwiki. Here it only makes sense if you can point out more specific bugs/improvements you note. I think that a possibility to collapse/hide the new TOC would indeed be a good idea. The design, on the other hand, is far from final atm, so I wouldn’t bother about that too much.

Ah, I suppose this is the place to comment. (I had posted this on T302046 but this task seems more appropriate) Feedback time!

That left-of-the-article TOC is a horrible nightmare. I absolutely hate it. I would seriously avoid any website that forced it upon me. Can't scroll it out of sight, can't collapse it, can't disable it, takes up too much space, I hate it I hate it I hate it. This was the reason I switched back to Vector classic on beta cluster. (and if Vector classic gets it too I'll switch to Monobook, Timeless or just murder it with a userscript) I'm not much of a fan of Vector 2022 (but it's not a lost cause, just needs work), but this TOC pushed me over the edge.

As a personal note: I rarely use the existing TOC. But I can scroll it out of sight so it doesn't bother me. If the TOC went completely missing tomorrow, I wouldn't miss it. Having this big, (to me) useless thing that contrasts with the main content (it's much darker) permanently in my field of vision greatly annoys me. And because of the fixed position, my banner blindness fails to kick in. This results in pure hatred for something that, on the face it, could seem innocuous.

I don’t think Phabricator is generally the right place for this type of feedback, there is a dedicated page for it on mediawikiwiki. Here it only makes sense if you can point out more specific bugs/improvements you note. I think that a possibility to collapse/hide the new TOC would indeed be a good idea. The design, on the other hand, is far from final atm, so I wouldn’t bother about that too much.

Thanks for the link, I added my comment at https://www.mediawiki.org/wiki/Talk:Reading/Web/Desktop_Improvements#I_hate_the_new_TOC. It's kind of confusing how some communication about development happens on-wiki and some on Phabricator. And the on-wiki page is not easy to find, "Reading/Web/Desktop Improvements" is not a title I'd ever think of to complain about a TOC, assuming I'd even think to check mediawiki.org to begin with.

I hate nearly any elements, on any site, with a fixed position. An exception is Cat-a-lot as it is very tiny, my choice to have, and it actually makes sense as Cat-a-lot can change more elements than those that fit on one screen . The TOC is not my choice (it would be great as a userscript, but not for me), it is far from tiny and since I hardly ever use the TOC to navigate a page it makes no sense to me either.

The contrast with the main content (the TOC is darker) made some sense with an inline TOC. It does not make sense with a fixed TOC. Actually it's lighter now than I remember. Also in my memory the TOC wasn't there when loading the page but suddenly popped into existence when scrolling down which was annoying. This was on betacommons where I no longer see the new TOC, but on enwiki beta the TOC now doesn't pop into existence. Either I remember it wrong or something changed. On enwiki beta I also see a fixed bar at the top now with search and userlinks which I don't recall seeing earlier. I'm no huge fan of a fixed top bar either, but it's easier to block out mentally. That top bar could have a button to hide/unhide (with persistence, like localStorage) the TOC.

Phabricator is really just about the specific technical solutions, not so much about programmatic communication about broader projects. As I said, you shouldn't bother about the design too much, it is far from final. The styling changes to new Vector are the final step of the Desktop Improvements project. Besides, I think that the current ToC is very ugly (and the new one is indeed unnecessarily similar to it), but I'm sure everything will get better. The important thing is the functionality.

Talking about functionality: how exactly does the new ToC deal with magic words like NOTOC, TOC and FORCETOC? And how is it affected by commonly used templates like Compact TOC or TOC limit? My tests were inconclusive, and I don't know exactly what the desired behaviour would be.

Talking about functionality: how exactly does the new ToC deal with magic words like NOTOC, TOC and FORCETOC? And how is it affected by commonly used templates like Compact TOC or TOC limit? My tests were inconclusive, and I don't know exactly what the desired behaviour would be.

@XanonymusX - the current expectation is that the ToC will respect all magic words and templates with the exception of the templates that change ToC Location (TOC_right and ToC_left), as these don't make sense with the persistent location

Sounds reasonable. However, I feel like most of the reasons for using NOTOC or Compact TOC atm become obsolete once a TOC is permanently shown next to the content. For example, while having a traditional vertical TOC for an alphabetical list is not very helpful and looks terrible, with the new TOC it would make more sense than the compact horizontal one (which is not permanently visible and thus harder to navigate). I wonder whether the behaviour could be improved in that regard.

Sounds reasonable. However, I feel like most of the reasons for using NOTOC or Compact TOC atm become obsolete once a TOC is permanently shown next to the content. For example, while having a traditional vertical TOC for an alphabetical list is not very helpful and looks terrible, with the new TOC it would make more sense than the compact horizontal one (which is not permanently visible and thus harder to navigate). I wonder whether the behaviour could be improved in that regard.

How about introducing something like "NOINLINETOC", would that work?

Hi, in my opinion table of contents in the new 2022 vector (which exists on the left menu bar) should have an scroll bar. By adding this capability, first, a user can see he/she is in what location of table of contents (near the top or near the bottom of TOC) and second, he can scroll the TOC more easily. I really recommend to add an scroll bar to the TOC by these reasons. Additionally, the word "Contents" should be outside of this scroll bar, and should not be scrolled at all, i.e., it (the word "Contents") should be displayed unrelevant to this fact that we are in what location of an article.

Hi, in my opinion table of contents in the new 2022 vector (which exists on the left menu bar) should have an scroll bar. By adding this capability, first, a user can see he/she is in what location of table of contents (near the top or near the bottom of TOC) and second, he can scroll the TOC more easily. I really recommend to add an scroll bar to the TOC by these reasons. Additionally, the word "Contents" should be outside of this scroll bar, and should not be scrolled at all, i.e., it (the word "Contents") should be displayed unrelevant to this fact that we are in what location of an article.

thanks for your thoughts. when you are scrolling the table of contents has a scrollbar. we tested having the scrollbar always visible and there were many complaints (link to feedback).

in the future please do not modify the task description before there has been a discussion. it can lead to confusion.

@alexhollender_WMF
No, if the TOC is very big, that is, it has many items, then:

  • The user confused with this fact that he is in what location of TOC.
  • In the case above, the word "Contents" does not appear to the user, and it is not clear that what is this space.

Please see TOC in the page https://en.wikipedia.org/wiki/Wikipedia:Village_pump_(technical) and test the above items to see what I mean. I discussed the above problems in that Village pump too. Thanks.

@Hooman_Mallahzadeh my apologies, I may have misunderstood your comment. are you saying it should work like this?

@alexhollender_WMF Yes like that, but the word "Content" should not be scrolled.

@alexhollender_WMF Yes like that, but the word "Content" should not be scrolled.

ok, thanks for pointing this out. I will create a task. can you explain why you think the word "Contents" should not be scrolled?

@alexhollender_WMF Because it is the title of this section, and such a title should be permanent to explain the its content. It is like the header of Wikipedia, that is a type of title too and the text "Wikipedia:Village pump (technical)" is displayed when scrolling hides this text from top of a page.