Page MenuHomePhabricator

[Epic] Improve the table of contents
Open, HighPublic

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
  • Section bolding - the section currently on the page will be displayed as bold. Users will be able to identify where on the page they are currently located by noting the bolding within the ToC
  • 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
OpenJdlrobson
OpenNone
DeclinedNone
Resolvedalexhollender_WMF
OpenNone
Resolvedovasileva
ResolvedJdrewniak
Resolvedovasileva
Resolvediamjessklein
Openiamjessklein
Resolvedovasileva
DuplicateNone
OpenJdlrobson
OpenNone
OpenBUG REPORTNone
Resolvedcscott
Resolvedovasileva
Resolvedovasileva
Resolvedalexhollender_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
Openovasileva
Resolvedovasileva
ResolvedEsanders
ResolvedSpikebwang
ResolvedBUG REPORTEdtadros
ResolvedJdrewniak
Resolvedovasileva
Resolvedovasileva
ResolvedEdtadros
Resolvedovasileva
ResolvedJdlrobson
Resolvedcjming
Resolvedovasileva
Resolvedovasileva
Resolvedovasileva
ResolvedEdtadros
ResolvedBUG REPORTJdlrobson
ResolvedBUG REPORTnray
ResolvedEdtadros
ResolvedBUG REPORTnray
Openjwang
Declinedjwang
Resolvedjwang
Resolvedjwang
Openovasileva
Resolvedjwang
ResolvedJdlrobson
ResolvedBUG REPORTovasileva
Openovasileva
Resolvedovasileva
Openalexhollender_WMF
Declinedovasileva
ResolvedJdlrobson
OpenEdtadros
Resolvedovasileva
Resolvedovasileva
OpenNone
OpenJdrewniak
OpenJdlrobson
ResolvedFeatureJdlrobson
OpenJdlrobson
ResolvedBUG REPORTovasileva

Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes
ovasileva triaged this task as Medium priority.Feb 8 2021, 1:42 PM
ovasileva moved this task from Needs Prioritization to Epics/Goals on the Readers-Web-Backlog board.

@alexhollender is this related to T277717 ?
it's hard to tell without the description.

@alexhollender is this related to T277717 ?
it's hard to tell without the description.

nope, the Sticky header and the Table of contents are two separate features at this point.

could you flesh out the description for future reference? maybe at least one line or a link or a prototype... anything ? :)

Clare began working on the table of contents feature flagging and we have realized while doing that, that T291098 is a blocker to this work.

Since Vector legacy and Vector modern skins are technically the same, it means we can't remove the table of contents from modern Vector in the code's current form without removing it from legacy Vector.

Shabe1234 set Due Date to Dec 14 2021, 9:00 PM.
Aklapper removed Due Date.
Aklapper added a subscriber: Shabe1234.
ovasileva raised the priority of this task from Medium to High.Jan 11 2022, 6:22 PM
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?