Requests for comment/Clickable section anchors

Request for comment (RFC)
Clickable section anchors
Component General
Creation date 2012-12-05
Author(s) MZMcBride, User:Krinkle
Document status in discussion
Implemented 2015-02 in gerrit:186332, but then backed out.
Seek comment from a designer (e.g. Brandon). Remove option 3. -- Tim Starling (talk) 00:20, 17 July 2013 (UTC)[reply]
See Phabricator.

This is a request for comment regarding clickable section anchors.


Currently, by using wikimarkup such as == Hello ==, it's possible to create an HTML header (in this case, an <h2>). This header can be referenced by an HTML id (in this case, the id would be "Hello" and the anchor would be "#Hello"). Currently, besides the table of contents box (if it's present on the page), there's no way to easily retrieve/re-use this anchor.


  • The hover state is not sufficient ("dying") due to use on touch screens (iPads, smartphones) etc.
    • What's dying is these simple minded approaches. Always optimise for the appropriate platform and take best practices into account. There is nothing wrong with hover. For accessibility a focus and click event should be attached as well (which automatically makes it work on touch devices) and one can further optimise for touch devices by supporting it with a click-and-hold, drag, press/click, swipe or whatever makes sense. --Krinkle (talk) 02:42, 20 January 2013 (UTC)[reply]
      • What's to say that in the future touch screens on such devices won't support hover states when your finger is near the screen (and not pressed yet)? Lack of support for hover might just be a transitional period for this type of devices, it's hard to say. GDubuc (WMF) 14:14, 6 January 2014‎
  • The [edit] link may be replaced by an icon or be moved to the other side.
  • RTL and LTR must be considered in any implementation.
  • Some headers on wikis contain links to other pages or URLs.
  • Mobile has collapsible headers with (dropdown) arrows and functionality applied, interaction design solution needs to consider this.
  • [edit] --> [edit | edit source] on VisualEditor enabled wikis
    Is this still true anywhere? --VEckl (WMF) (talk) 02:33, 24 March 2016 (UTC)[reply]
    Yes, because Single edit tab is not deployed everywhere, plus it allows editors to keep the 2 tabs as an option. –Quiddity (talk) 20:50, 16 April 2016 (UTC)[reply]
    I'm not referring to the Single edit tab feature, but to the [edit] links aside of headers in the content? Has there ever been an implementation where "Heading [edit | edit source]" has been a widely implemented thing?
  • Some users get annoyed with animation as they scroll down/through an article
  • Screen readers should not be affected negatively, as in reading an anchor link element out loud on every heading – compare Option 1 and 2. Uncertain about Option 3
  • Balancing discoverability and distraction, also ensure color contrast is WCAG 2.0 level AA
  • The ToC is only added automatically if there are more than 3 headings. For pages with 1-3 headings, it is not possible to easily obtain a section link.

Proposed implementation[edit]

A clickable symbol in the content margin. (E.g. §, ¶, #, Link icon.svg, etc, see #Iconography? below)

Chain link icon.png  Header [edit]

Header   [edit]


  • Widely used design pattern, such as here on MediaWiki using the HeadAnchor gadget (1st section, last item) (using this .js and .css code), and elsewhere (see #Iconography? below)


  • The content margin ("gutter") has very little space; depending on skin, it is only 1 to 1.5em wide, and is even dynamic in Vector.
    • Place anchor inside/after the heading (like second example)?
    • Use a very small anchor icon?
    • Widen the available space by increasing the content margin?
  • How would click-to-togggle-visibility work for touchscreens?

Open questions[edit]

Target demographic[edit]

First of, who is in need of this feature? Who are the users?

Only when this feature is a clear improvement for the majority of our users – without bringing confusion or slowing them down in their tasks (like impairing reading fluency, at skimming a page or finding the edit link) – it is useful to implement.

Is it probably just a power user feature, that doesn't need to be in core or doesn't need to be activated by default (optional user setting)?[1], [2] --VEckl (WMF) (talk) 08:23, 24 March 2016 (UTC)[reply]

“I can understand that the most people do not need this feature, so the best way is it to implement it as option or gadget. I personally use it longtime as gadget from @Schnark […]” [3]
I have the gadget enabled on mediawiki, and I miss it on other wikis (where I have to use the workaround of: scrolling up to the top of the page and clicking in the ToC). I use it to obtain links (from the browser address bar) for sharing (email/IRC/phabricator/twitter/etc), and sometimes to obtain links for onwiki content creation or discussions (if the former then I have to remove the underscores manually and fix any percent-encoding; if the latter I usually do the same, but not always due to laziness). I use the functionality (or try to at other wikis) about 3 times a week, and have done so consistently for many years. Quiddity (WMF) (talk) 00:50, 7 April 2016 (UTC)[reply]
Statistics on gadget “vector-headanchor” usage among others on --VEckl (WMF) (talk) 05:58, 18 April 2016 (UTC)[reply]

All the examples given in this task discussion so far has been technical documentation[4] [5] [6] and in one case legal text[7]. Is this, because the usage of section links is much more needed or because it address a special engineering/judicial thinking?

Do we have implementations in text heavy sites apart from those, NY Times seem to have abandoned their try again [8]? --VEckl (WMF) (talk) 08:23, 24 March 2016 (UTC)[reply]

What to share/copy[edit]

wikilink, ID, or href (full URL)?

  • Pro: To accomplish possibly broadest usage (think social media sharing) a full URL seems advantageous --VEckl (WMF) (talk) 08:23, 24 March 2016 (UTC)[reply]
    • We do not want to override the OS clipboard (we don't want editors to accidentally overwrite multiple paragraphs they were storing there, due to an accidental click). We just want to update the browser's address bar (as the MediaWiki gadget does), or provide a copyable string (as the Frwiki gadget does). Quiddity (WMF) (talk) 00:57, 7 April 2016 (UTC)[reply]


Should it only appear on-hover, or always be visible? (Findability versus distraction)


  • Is there an icon that works globally as clear identifier for this proposed action applied to it?
  • If not, can we choose a global default, but enable an easy per-wiki override? (Probably, per phab:T18691#1097802.)

Discussions on which icon:

  • Section sign: §
    • Uses: Implementation example at W3C on right side[9]
      Implementation example at W3C before the heading on the left[10]
    • Pro: "I propose to keep using the "§" symbol: it's not what I originally proposed, but we already tried it and we saw it's mostly well-received. It's correct and used in any text which needs to refer to sections, not only laws (also in German; [example for non-legal usage has been received as not appropriate in current times further down])."[11] Enwiki's w:en:template:See also automatically converts # into § .
    • Con: In some languages mainly just used in legal context (German, Norway, Polish)[12][13][14] & [15]. I fully agree with that, in German language, it's nowadays used exclusively in judicial context --VEckl (WMF) (talk) 08:23, 24 March 2016 (UTC)[reply]
  • Link chain icon: 🔗 (unicode) or Link icon.svg (image)
  • Bookmark icon: 🔖 (unicode) or Bookmark icon.svg (image)
    • Uses:
    • Pro:
    • Con: Link chain icon more intuitive [25]
  • Anchor icon: ⚓ (unicode)
    • Uses:
    • Pro: [26]
    • Con: [27]; Technology-driven metaphor, doubting that most people who haven't been working with HTML directly, are aware of “anchor” metaphor. --VEckl (WMF) (talk) 08:23, 24 March 2016 (UTC)[reply]
  • Number sign: #
    • Uses: [28]
    • Pro: Clicking the link will add "#foo" to the URL, so this option is somewhat logical.
    • Con: Used in wiki markup as number list item. Widely used in connection with hashtags.
  • Paragraph sign/pilcrow: ¶
    • Uses: [29][30]
    • Pro:
    • Con: We're Not actually linking to individual paragraphs.
  • The section's numbers themselves: 1.2.3
    • Uses: [31]
    • Pro: We already have "Auto-number headings" in Special:Preferences#mw-prefsection-rendering (default-off), and we could just make those numbers into links (and perhaps reduce their size, and color them grey, to distinguish them from content), if we decided to not make this a default-on feature.
    • Con: Would probably have to be default-off, and thus vastly less discoverable, due to ambiguity and size. Would probably have to remain permanently-visible (not use a hover state) due to expectations from current users.



Alternative (rejected) implementations[edit]

Option 1

Another [bracket] element for the anchor link ("#" used as example, but any icon is possible)

Header [#] [edit]

Header [#] [edit]


  • Added complexity next to every header, when we want to draw focus to the [ edit | edit source ] links.
    • Adding to that contra argument, the edit link is the most important link for the concept of a wiki, it has and should have an exceptional position in the user interface. --VEckl (WMF) (talk) 01:42, 23 March 2016 (UTC)[reply]

Option 3

Just make the header a link? This would be trivial to implement, presumably.



  • some headers already are or contain links.
  • degrades readibility
  • typographically "bad"
  • Inconsistency between this (a link which links directly to itself), and all other wiki links.

Option 4

task T18691#1007830 Why not just a right-floating icon/link (where the edit button used to be?) That would be the easiest to code. -Edokter

Link icon.svg Header [edit]

A right floating link would certainly be easier to code, but would that not clutter up the right side of heading too much? I always thought even the edit link looked slightly out of place, but that's just my view. Also, if the few people are already using the Headanchor gadget (I don't know how many, of course), would it not help to keep the behaviour consistent? -polybuildr
Since the [edit] link has moved to the left two years ago, there is no clutter on the right side. As the anchor link need not be as prominent as the [edit] link, I don't think it is out of place there, especially with :hover. Plus, any gadget that may add any right-floating element to the header will ensure they play nice with eachother. -Edokter