We need a better Table of Contents. (T114051) We need to determine who the people holding the stakes are and we need to find a path forward.
**Specific pain points with the current table of contents implementation**
* Caching problems due to partial i18n (it's treated as part of the content, but localised)
* Improving it is unnecessarily difficult (source is scattered across several different classes), and patches improving it are also quickly obsoleted by unrelated changes due to how spread out it is
* Extensions cannot easily reuse it (technically it is possible to replicate the several different calls required to generate its html, but it's a mess and results in duplicate ids and stuff - Extension:DeToc, Skin:BlueSky, and others all do this)
* Extensions cannot hook into it to modify it or reuse it for different content models
Extension use-cases modifying/adding to the ToC:
* **Parser extensions dealing with particularly long, sectionable content.** A discrete example is the ScreenPlay extension, which introduces a parser to render screenplay formatting. This includes scene headings, which would ideally appear in the table of contents as, well, the contents of the page (part of T114033). As is, however, even ordinary == == sections within the screenplay tags do not appear within the table of contents because it is being parsed separately from this part of normal wikitext. Currently there is no way to hook back into the table of contents and fix this for either case.
* **Formatted discussion extensions, which implement sections for different threads.** LQT got around this by just making its own. Flow gets around this by not having a ToC at all (unless it also just implements its own now; I haven't checked recently). While they can get away with this due to replacing all the usual content on the page (and thus avoiding ever having two ToCs), this is not ideal. They should be able to hook into the core table of contents and reuse that, not reinvent the wheel in a different way every time.
* **Anything else that wants a ToC of unusual content.** Books (T33075, T78329), Special pages (T15862, T113459), preferences, whatever.
If special pages and whatever could also register sections with a standard ToC object and place that on the page, this would standardise output for all of them, regardless of what generated the content.
Reusing the ToC:
* **Skins such as BlueSky, Naiad, and Refreshed, which incorporate the table of contents into their interfaces.** This is currently possible, but incredibly hacky, and it does not persist even on edit. There are also issues (when using more than one) with duplicated id's because all the HTML is pretty much hardcoded into the output.
* **Multiple tables of contents on a page.** For when you're insane or dealing with insanely long pages. Or have multiple pages on a page or something.
* **Getting a ToC for a page by title.** Possibly useful for semantic stuff. Or generating contents for see also links. Or for the skins mentioned above. Or for the API. Having a single object to interact with should vastly simplify the process whether it exists already or not.