Page MenuHomePhabricator

[L] [SPIKE] Add configurability options for table of contents
Open, HighPublic5 Estimated Story PointsSpike



In Legacy Vector you can configure how sections and sub-sections display in the table of contents using Template:TOC limit. Currently in Vector 2022 there is no such equivalent for the table of contents.

In T300973 we made it so that top level sections in the table of contents dynamically expand/collapse their sub-sections based on how many total sections & sub-sections are in the article. However this approach does not always yield the best table of contents presentation, particularly for pages that have many sub-sections that are all nested within a single parent section. A clear example is Wikipedia:Closure requests.

image.png (1×2 px, 407 KB)


Think about how we could introduce some kind of configurability that allows editors to customize the display of sections and sub-sections in the table of contents (similar to Template:TOC limit). A simple starting point might be a single option that forces all sections in the table of contents to be expanded by default. As an example, the result of this preference being turned on for Wikipedia:Closure requests would be:

Screen Shot 2022-09-14 at 5.45.46 PM.png (818×1 px, 352 KB)

This should be possible to be done on a per-page basis e.g. via magic word

Acceptance criteria

  • Review and come up with a couple of options on ToC configurability (specifically for introducing a way/magic word to show all sections)
  • Talk to the content transform team to understand how this might work and what constraints we have
  • Ideally this would only effect modern Vector (and other skins using the new table of contents) and the legacy table of contents would be left unchanged., As part of this spike we should confirm that can be done.
  • Summarize findings on this ticket.

Event Timeline

alexhollender_WMF renamed this task from Add configuration for table of contents to Add configurability options for table of contents.Sep 14 2022, 9:46 PM
alexhollender_WMF created this task.
ovasileva triaged this task as Medium priority.Sep 15 2022, 9:01 AM

Moving this to the board to discuss possibilities. Not a blocker for deployment.

ovasileva renamed this task from Add configurability options for table of contents to [SPIKE] Add configurability options for table of contents.Sep 15 2022, 5:11 PM
ovasileva updated the task description. (Show Details)

This would require changes in the parser, potentially replacing this workaround here:

LGoto set the point value for this task to 1.Sep 29 2022, 5:16 PM
LGoto renamed this task from [SPIKE] Add configurability options for table of contents to [SPIKE] Add configurability options for table of contents (L).Sep 29 2022, 5:27 PM
Jdlrobson renamed this task from [SPIKE] Add configurability options for table of contents (L) to [L] [SPIKE] Add configurability options for table of contents.Sep 30 2022, 7:55 PM

While reading up on the discussion about vector22 I ran across this Task because it was recommended to User:Yomomo. While reading the above description I noticed something I'd like to share. I wasn't sure where to add it, but I think as it's mentioned above, here should be fine. Feel free to move the comment to a more appropriate place. Notification in this case would be nice.

Above: " ...and the legacy table of contents would be left unchanged..."

When deploying Vector22 most configurability of the TOC will be lost (e. g. placing it on the right hand side) hence nobody will use it anymore, so deploying vector22 will affect legacy table of contents anyways.

My proposal for a solution or "workaround" would be: make or use a magic word to fall back to legacy table of contents if the editor wishes to.

Thanks, regards, HirnSpuk

Jdlrobson added a subscriber: Mabualruz.

@Mabualruz we've decided to descope this work for now so we can focus on page tools.

Restricted Application changed the subtype of this task from "Task" to "Spike". · View Herald TranscriptDec 14 2022, 10:50 PM

This seems to be being rapidly deprioritized, if I'm reading the meaning of 'Spike' correctly. It should be a high priority. TOC limit is used on 22,000 pages for a reason - they are generally high profile pages with something exceptional happening section-wise, and they need to display the same behavior in Vector 2022. Otherwise, page usability will be severely impacted. It's an exceedingly useful tool for readers and editors alike.

Vector 2022's default of having top-level headings visible only, and all others being "clicked into", just does not work for many pages.

Related question: do the magic works ___TOC___ ,___NOTOC___, and ___FORCETOC___ work in Vector 2022 as they do in Vector 2010? Thanks.

I don't particularly think toclimit is necessary with Vector 22 because of how the table of contents functions in the skin. There might be other templates to look into regarding tables of contents, but that's not one of them, because the user can decide how many sections are displayed.

How exactly can a user decide how many sections are displayed? Could you point to a help page describing this? Use wikibooks as an example, perhaps: Perfect example I think because when switching the skins to legacy vector the original intention of the author becomes quite obvious and the idea is totally lost in V22.

If this would be all... I'm not even able to usually see the toc in Vector22, because of the main menu I'm heavily using, which is kind of 'large' in german wikibooks. The usability of the old toc is totally lost. I can't get an overview of the things I'm going to see on the page. It's a simple navigation tool now ("where am I and what was the previous section and what comes next" instead of "what is on the page, or what does the editor want me to see about the pages structure"). Everybody interested in getting an idea what I'm talking about: take a look at 1. Use Vector 2022 and try to see, if you can judge, what topics are discussed with what headings; then, 2., try the same with legacy Vector. I think the flaw is pretty obvious. Although, we are talking large toc not deep toc here.

But the question at hand is: "add configurability..." so, giving the editor at least a possibility to limit the toc-depth would be nice. Regards HirnSpuk

FWIW and to provide another perspective I don't see this as a flaw! Seeing all the headings in seems helpful to me. While this might be useful for an editor, as a reader, I often skip reading articles with short table of contents because I either expect them to be poorly structed (too verbose) or lack content (too short). That article in legacy Vector is a little deceiving as it gives the illusion that the article is less complete than it really is.

Screen Shot 2023-01-25 at 4.53.51 PM.png (422×578 px, 46 KB)
. {F36511048}

Putting aside mixing "articles" and "chapters", you seem to be coming from the impression of "flaw of content" which you judge from the table of contents, correct? That's another topic in my opinion. And it only works for rather short articles. Try and see, how useful the original toc and the new toc are there. And Btw: because of the default fold-in toc your argument would kind of work for the new toc on the given link as well, at least if you are not interested in clicking the little arrows. Though I'm not totally clear, when the toc is folded by default, because in the tennessee-link it's not. Best regards

When compiling toy models to support, please include a page that consistently has ~100 sections (like an active noticeboard or talk page). For these a common way to browse is by skimming across section titles in the TOC. Being able to do that without locating and scrolling inside a tiny TOC (e.g., by paging down the central page content instead) is useful.

For these an easy solution would be supporting a template or magic word that forces the TOC to render in the body text.

Jdlrobson changed the point value for this task from 1 to 5.Feb 1 2023, 6:46 PM

There is also a need for an option (I think it should be the default) to expand sections one level at a time. Currently, when a level 2 header in the TOC is expanded, all the sub-headers are shown, no matter their level. This runs counter to traditional TOC UI design, in which only the next level down is expanded. It is particularly unhelpful on long disambiguation pages, which rely on scanning the TOC level by level to narrow down one's search, but the problem is not limited to dabs. It's exacerbated by the lack of numbering or vertical lines for following the indentation level, for which I believe there are separate tickets - but in most cases, one-level-at-a-time expansion would go a long way to mitigating the visual level-tracking problem.

Given the title: is this the right place to discuss NOTOC / FORCETOC magic words?

In T317818#8596042, @Sj wrote:

Given the title: is this the right place to discuss NOTOC / FORCETOC magic words?

yes, please add any thoughts you have about magic words

Then I'll add my ideas: I would like FORCETOC and NOTOC to work like the old behaviour; TOC → shows the TOC as it was in legacy Vector. This might even make sense additionally to the new TOC. They both have their benefits. I really would like the common template TOCright to work. The TOC should be able to be printed out. At least on demand. Anybody saying that isn't possible, I need to ask: why did this work until recently with "hiding" the TOC by accident, as it seems(?). Best regards

@HirnSpuk : agreed. Do you think we need separate magic words to specify showing or not showing the sidebar TOC?

Also useful:

  • A magic word for expanding the sidebar TOC by default.

@Sj, good question, I personally wouldn't bother, because the side-bar-TOC is out of content bounds anyways (one reason I don't like it) and making this 'too' configurable would add only workload, but no benefit as far as I see it. But I might miss something and I see the idea of limiting/configuring it, see my reasoning above. My main concerns (things lost compared to legacy Vector) are "printout", "using the TOC in full width" and "using on the right hand side of the page". All three points have benefits, I personally would not want to miss. Though I do understand, that they are mostly if not completely irrelevant for displaying encyclopedic content. But other projects and community pages will benefit greatly from such a behaviour (at least the way I see it). Just take a look at template TOC right, which is used on thousands of community pages alone on english wikipedia. Regads

ovasileva raised the priority of this task from Medium to High.Feb 17 2023, 10:27 PM

We respect a number of magic words like NOTOC / FORCETOC from backend side but we only set flags for those ex: Parser.php $mShowToc, we could introduce more magic words and flags, and handle them individually. but imho we should have the parser extract all magic words into an data array, then skins and api's could make decisions on those as the case requires.

This still needs more insight this is just from a quick check on the magic words related to TOC.

We’re still evaluating the scope of the desired changes to the TOC, so to that effect I’d like to summarize the concerns and requests laid out in this ticket so far:

Editors would like editorial control over the following:

  1. Whether the TOC is expanded/collapsed by default
  2. The depth of the TOC subsections
  3. Whether the TOC is rendered in-content (as in legacy Vector) or in the sidebar by default.
  4. Fine-grained control over expandability & numbering of the TOC.

We can create new magic words to address a few of these scenarios:

  1. __TOC_EXPANDED__ and __TOC_COLLAPSED__ to expand/collapse the TOC by default.
  2. __TOC_LIMIT_1__ __TOC_LIMIT_2__ …6 etc. as a replacement for [[Template:TOC limit]].

However, if we were to create these, I’m not sure that making them skin-specific is a sustainable approach (per AC#3 in the task description). __TOC_COLLAPSED__ for example, could function in both legacy and modern Vector, albeit differently: in legacy Vector it could be the equivalent of pressing the [hide] button, and in modern Vector it would show the top-level TOC sections (not sure if that makes sense from a design perspective). __TOC_LIMIT_*__ could be equivalent in all skins though.

Regarding more fine-grained control in general, if we were to enable the rendering of the TOC in-content, via the __TOC__ keyword, that would largely restore most of the existing customization from legacy Vector that’s done via templates. That’s because most templates use the __TOC__ keyword wrapped in some custom CSS.

In this scenario, if editors use the __TOC__ keyword, we could disable the new TOC in modern Vector and print the old TOC in the content instead. This might better address scenarios where long headlines are common like on talk pages (we have tried to address this by making the TOC wider when it’s pinned T316056, but that’s only for that one state).

It may be helpful to distinguish (as separate issues)

a) new magic words -- takes thought, as new feature requests
b) continuing to support NOTOC and TOC -- avoiding a regression, which may be breaking current templates and workflows