Page MenuHomePhabricator

[L] [SPIKE] Add configurability options for table of contents
Open, MediumPublicSpike



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

There are a very large number of changes, so older changes are hidden. Show Older Changes
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

It has been mentioned in other places before, but I don't see it mentioned in this task, so I wanted to point it out once again. There is a specific situation in which both the custom TOC in the article and the normal V22 TOC should be displayed. For example, in this list, the TOC is shown at the beginning of the article through a specific template, but because of the current use of NOTOC, there is no left-side TOC in V22, even though it would be very helpful when scrolling. Similarly, alphabetical lists on dewiki regularly work with such horizontal TOCs. It should be possible to display both a custom TOC and the standard one in V22.

Hey @XanonymusX - how exactly would you imagine that working given the NOTOC directive works cross skin? I wonder if one approach might be to drop the NOTOC directive and instead use a template to hide the TOC on legacy Vector instead (and thus show it on Vector 22)?



where that outputs

<div style="display:none">__TOC__</div>

Exactly, there needs to be an alternative to NOTOC. A suggestion would be a magic word specifically for this use case (NO_INLINE_TOC or something like that). But the template suggestion sounds interesting as well. So you mean that the TOC will be forced to be invisible in the content? It seems a bit hacky, but if we are sure that it won’t break anything, I could introduce such a template on dewiki and replace the NOTOCS in relevant templates/pages.

It seems a bit hacky, but if we are sure that it won’t break anything, I could introduce such a template on dewiki and replace the NOTOCS in relevant templates/pages.

I think this is how most of the existing templates work e.g. TOCLIMIT (but usually they are changing the styling) but that would be the quickest way to get the table of contents into Vector 2022.

I think a better long term solution would be to have a magic word to generate the horizontal TOCs in the software rather than tempaltes e.g. SECTION_TOC_HORIZONTAL - perhaps when that's used it disables the main table of contents in the article, but doesn't remove the one in the sidebar.

Yes, that sounds good. I have implemented the template solution in Template:Nummer-eins-TOC for now, seems to work fine! Will check whether I can expand the use of this solution on dewiki.

Regarding NOTOC, I suspect we're going to need either a magic word like {{CURRENTSKIN}}, or something like NOTOC10 (for Vector 2010), and NOTOC22 (and maybe NOTOC17 ?).

An example of a case where this would help is in this discussion, regarding the en-wiki template Compact TOC's use of NOTOC which has consensus (developed while Vector 2010 was the default), but with the advent of Vector 2022 results in the suppression of the ToC from the left sidebar, which is an undesirable result according to one user who argued in the discussion that Compact TOC must be changed to prefer the new skin. Providing the magic words (or other property) that templates could query, would help resolve this problem to the satisfaction of all, without advantaging one skin over another.

My proposal is injecting a magic word as {{TOCLIMIT:1}}, {{TOCLIMIT:2}} ... or {{TOCLIMIT:6}} etc into article.

This ticket was in limbo - it was in archived sprint. Not sure what work is remaining for it.

ovasileva lowered the priority of this task from High to Medium.Jul 18 2023, 9:24 PM

Most recent occurrence that I am aware of is at Template talk:Skip to bottom. We're struggling to come up with work-arounds; this one may be amenable to a common.css update, but that only fixes it for one user at a time, and only applies to this one case.

See also mw:Talk:Reading/Web/Desktop Improvements/Archive9#Magic word, built-in, or testable property needed.

I assume the move to backlog and reduction of priority means we won't see any movement on this for the foreseeable future. This is continuing to bubble up at Wikipedia from time to time, and to some extent is unnecessarily raising tensions or driving a wedge between users of legacy skins and those using the default Vector 2022.

Edited: @Izno has added a proposal that should resolve this for the Skip template noted above.

Wikipedia:Manual of Style/Accessibility suggests using Template:TOC limit in some cases, but this still seems to be broken for Vector 2022. I was wondering if there was any progress on this? (T333017 doesn't mention any details, including whether it will address the TOC limit issue, and it also looks like it might have stalled?)

Something like the __TOC_LIMIT_1__ or {{TOCLIMIT:1}} suggestions above seems uncontroversial, and doesn't seem to be blocked by any of the other issues raised.

Fine-grain TOC control seems like it could be treated as a separate task? I haven't seen any suggestions for how to implement this yet; one way could be to add syntax (maybe something like __TOC_HIDE_SECTION__ below a section heading, or just -== This ==- ) for headings that will be collapsed by default in the sidebar TOC, and won't show up in the inline TOC? This could also address the accessibility issues of pseudo-headings raised in the enwp MOS, in cases where a TOC limit wouldn't be enough.

The other issue, of allowing inline TOCs to be displayed instead of/as well as the sidebar TOC/as a horizontal TOC/etc., again seems like a separate non-blocking task.

See TemplateStyles workaround suggestion by @Izno (last July) and implementation by @SilverLocust today (diff, and earlier :en:Template:Skip to bottom/styles.css).

See TemplateStyles workaround suggestion by @Izno (last July) and implementation by @SilverLocust today (diff, and earlier :en:Template:Skip to bottom/styles.css).

@Mathglot I may be missing something, but I think the "Skip to TOC" (#toc) link having no purpose with Vector 2022 is a different subject from this ticket, which is about when subsection headings in the Vector 2022 TOC are shown or collapsed.