Page MenuHomePhabricator

Gadget API for adding buttons to section titles
Open, MediumPublicFeature


There is a lot of variation to how sections are handled (skins change it, Minerva has collapsing sections, Parsoid HTML might or might not have <section> wrappers making sections easy to identify, DiscussionTools changes section headers significantly, Flow does its own thing) which makes a section-level entry point challanging to do in a robust way.

It would be nice to have a stable API for gadgets which provides the following functionality:

  • Access TOC data (list of sections, with level, HTML ID / anchor, plain text of the section title (either the wikitext or the plaintextified HTML))
  • Add a button with a click handler to a specified section. On most skins this might look like the [edit] link, on Minerva it might use some sort of icon; or maybe just take an arbitrary DOM element and plug it into the right place.
  • Maybe section collapse/uncollapse functionality if the skin supports it.

Event Timeline

The specific use case where we ran into this was adding a button to section headings in T336692: Tool to summarise sections on a wiki page , which had to be done in several different ways for different skins and talk vs. article page. (cc @Alexey_Skripnik who did that work.)

Jdlrobson triaged this task as Medium priority.Jun 14 2023, 9:26 PM

I wonder if the work @matmarex is doing would lend itself to this kind of API?

How so?

The work in T13555 is changing the heading HTML so I assume any gadgets appending to the heading are likely to be broken/impacted. This might be a good opportunity to create and advertise a helper function e.g. mw.util.addHeadingLink( 'First_heading', node );

No worries if not, just a passing thought.

Given the issue in T358452 and some of the recent gadget breakage I am a little worried about code interacting with section headings and would feel more comfortable with an API that is compatible with both the old and new HTML. Would the content transform be interested in prioritizing this work as part of the section heading changes in T13555? Perhaps the web team and content transform team could work together on this one as part of a solution to T358452 ?

Here's some napkin pseudo code that might be useful to create and allow access and safe manipulation of sections.

interface Section {
   constructor() {
      /** HTMLElement representing heading associated with section */
     const heading
     /** @type {number} of associated section */
     const editSection;
     /** HTMLElement|null representing section tag - null in legacy parser */
    const element;

   /** Allows creation of actions alongside edit link */
    createNewAction( label, iconName ) {
        return HTMLElement;

// returns an array of all Sections representing headings.
const sections = mw.util.getSections();

// returns element matching CSS selector
const section = mw.util.getSections( '#id' )[0];
const sectionsH3Only = mw.util.getSections( 'h3 );

@ssastry this is the task we discussed today. If we (perhaps with @matmarex ) could work on this in early April, we think it would mitigate various problems we'll see in MobileFrontend and will soften the blow of gadgets breaking (which often web team is blamed for). MobileFrontend will likely change the HTML format further to support section collapsing for example so having a stable API seems like a good thing for both our teams on the long run.

If you want to work on this, I think it needs to start with inventorying the existing gadgets to inform the design of the new API. Otherwise we risk spending time on something that doesn't actually serve the practical use cases. Until that happens, we need to continue supporting the de facto API of the .mw-editsection CSS class and associated markup.

@matmarex yes that would be a good starting point. A specification of what's needed would be useful.

A crude global search suggests there are about 1,548 gadgets/user scripts that might be impacted e.g. reference h2 nodes:*%5C.js

I started de-duplicating gadgets (ignoring user scripts for now) and I see the following people may have insight into gadget needs based on gadgets that might be manipulating the HTML of section headings so I would be curious for what requirements they'd have for an API that needs access to sections:
@DannyS712 @MusikAnimal @Nux @AlexisJazz

This is very interesting. Yes, I hack your HTML a lot. It's pretty maintenance-intensive. adds multiple buttons/links. (configurable, but it can add like six or seven max I think) Especially because I aim to support all skins, including Minerva.

Some quick thoughts:

  • The obvious: specify:
    • label/link name
    • .classes
    • #id
    • event(s)
    • which section(s) to add the link/button to
  • Easy access (html data attribute?) to:
    • Section title in plain text.
    • Anchor for section.
    • Actual wikitext for section title. This would be GREAT because right now I do something like this:
      • Get innerText section title from HTML.
      • Get wikitext.
      • Search wikitext for sections (search the Factotum code for (?:^|\n)[=]+, you know how it is)
      • Put it through flattenWikiText(), e.g. FTT.flattenWikiText('==Check this [[link]] it\'s \'\'\'awesome\'\'\'==') => "==Check this link it's awesome=="
      • Compare that to the innerText. It's WAY more complicated but you get the idea here.
      • "Hey AlexisJazz, Y U NO use section number?" Because section numbers can change. Random archiverbot shows up after you loaded the page -> all section numbers invalidated.
    • This is probably a stretch, but if we could have the page title from the page the section is from (in case of transcluded sections), yeah, that would be GREAT.
      • Sorry, not thinking straight, I was thinking of sectionless transclusion which is obviously not something that can be resolved with this. Nevertheless, the page title for the section should be available similar to how you can extract that from the edit section link currently.
  • Also consider .firstHeading which is section 0
  • Allow adding an empty div with some id/class for maximum flexibility. For example, some gadgets/scripts could wish to add a dropdown instead of a button to a section title. You can't accommodate for such specific needs, so just allow the addition of an empty div that the script could populate itself.

@Schnark may also be interested as I think also did this. @Qwerfjkl may be interested as well.

Also @Jack_who_built_the_house for

@AlexisJazz Thanks for subscribing.

I want to talk about placing of the section buttons. Initially, Convenient Discussions added section buttons to the side of headings, inside [ edit ]:

image.png (735×1 px, 102 KB)

They even had disabled/pending/hidden states.

Later, Vector 2022 emerged with its narrower content area and DiscussionTools with its decorations. This is when I decided to get rid of the section buttons next to "edit" and moved all section actions to the metadata bar which I borrowed from DT. The reasoning for that is that if you have a long enough heading, it will quickly wrap to the next line and look something like this:

DiscussionToolsConvenient Discussions
image.png (179×1 px, 29 KB)
image.png (245×1 px, 27 KB)

Probably it's less critical to articles with no "Subscribe" button, shorter headings and smaller font for them (and no metadata bar where you can shift the menu to). But at some point you may find yourself in a situation with buttons occupying the valuable area between the heading and some right-floating image or infobox. Example of an article at 1500px window width:

image.png (355×973 px, 139 KB)
(Note "quick edit" from QuickEdit.)

(Side note / offtopic: given that Vector's sidebar header buttons now look differently, maybe it's time to change the look of section buttons as well, moving away from this [ bracket style ] inspired by text-based UIs?)

image.png (51×157 px, 1 KB)

Thanks for pinging me. I've also had difficulty modifying section headers for my script CFDLister - I had to draw on my limited JavaScript knowledge to make a dropdown in the section header (
With a few scripts running together section headers can easily get messy:

image.png (314×1 px, 92 KB)

Hi. I specifically moved buttons away from section headers recently and into a template we can control locally (on wiki). This has drawbacks -- I needed to add section names to the template... but also again something we can control locally, not something that might change with a skin or MW update.

So this kind of works for our del requests, but is not ideal:

obraz.png (274×694 px, 32 KB)

I mostly agree with what AlexisJazz said. I don't think I would need to be able to get wikitext though (I assume getting wikitext would be async, so slow). I would need to be able to get an HTML fragment (e.g as a list of elements inside the section.

So this would definitely not work for me:

 /** HTMLElement|null representing section tag - null in legacy parser */
const element;

If I need to worry about which parser is used then I would prefer not to have this in the interface at all. But, as mentioned above, I would also love to have the Section.elements accessor instead :)

I should mention that what I would actually love to have is <section> or any kind of parent/wrapper of the elements in the section. That would make many such things as nominations easier (del requests, good article, dyk article etc).

Jdlrobson lowered the priority of this task from High to Medium.Wed, Apr 3, 6:26 AM