Requests for comment/Clickable section anchors

This is a request for comment regarding clickable section anchors.

Background
Currently, by using wikimarkup such as, it's possible to create an HTML header (in this case, an &lt;h2&gt;). 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.

Considerations

 * 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)
 * 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)
 * 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)
 * 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
A clickable symbol in the content margin. (E.g. §, ¶, #,, etc, see below)

 Header edit

 Header  ¶ edit

Pros:
 * 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 below)

Drawbacks:
 * 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?

Target demographic
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)? , --VEckl (WMF) (talk) 08:23, 24 March 2016 (UTC)
 * “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 […]”
 * 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)
 * Statistics on gadget “vector-headanchor” usage among others on mediawiki.org --VEckl (WMF) (talk) 05:58, 18 April 2016 (UTC)

All the examples given in this task discussion so far has been technical documentation  and in one case legal text. 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 ? --VEckl (WMF) (talk) 08:23, 24 March 2016 (UTC)

What should happen on-click

 * 1) Just update the browser-URL (and push the heading to the window-top)?
 * 2) * Pro: This is the outcome in most external usages of this concept.
 * 3) Copy [something] to clipboard? (see section below)
 * 4) * Con: We do not want to override the user's 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).
 * 5) * Note: The new-in-2023 Extension:SectionAnchors has 3 auto-copy features (click, ctrl+click, shift+ctrl+click) documented at their site.
 * 6) Open a popup-modal-window with options?
 * 7) * Pro: The desired option per Proposal #2 in T18691.
 * 8) * Pro: Provides a logical location for the other regularly-requested feature of direct platform-share links, cf. Social media plugins and most of the links there.

What to share/copy

 * 1) wikilink
 * 2) * e.g.
 * 3) * Pro: Frequently needed by editors. Otherwise we have to manually remove the _underscores_ from a copied URL, or copy the Page-title and Section-heading separately.
 * 4) ID
 * 5) * e.g.
 * 6) * Con: Not as commonly needed by editors, and would significantly enlarge any options window.
 * 7) href
 * 8) * e.g.
 * 9) * Pro: To accomplish possibly broadest usage (i.e. social media sharing) a full URL seems advantageous.
 * 10) Permanent link
 * 11) * e.g.
 * 12) * Pro: Already exists as a default "Page Tool" in the sidebar of every page.

Should there also be other/replacement options on translatable pages?
 * 1) wikilink
 * 2) * e.g.
 * 3) href
 * 4) * e.g.
 * 5) * Pro: see T330922 - Provide easy access to MyLanguage links for translated pages

Visibility
Should it only appear on-hover, or always be visible? (Findability versus distraction)
 * 1) On focus (Patch)
 * 2) * Con: Frustrates some readers/editors who dislike the distracting appearance/disappearance as they scroll.
 * 3) * Pro: Less visual noise during normal reading.
 * 4) * Pro: Commonly used in external implementations.
 * 5) If always visible, how strong?
 * 6) * Note: Intended patch, which targeted to decrease contrast. Must take into account color contrast requirements!
 * 7) * Pro: Removes the animation frustration issue.
 * 8) * Pro: Consistent for touch-screen users.

Location
Should it be located:
 * 1) Before the heading?
 * 2) * Pro: Reduces interference with existing location of [edit] links.
 * 3) After the heading?
 * 4) * Pro: Reduces the edge-cases for headings within box-designs which can cause the anchor-link to overlap with the border.
 * 5) After the [edit] link(s)?
 * 6) * Pro: Logically a part of an 'interaction'.
 * 7) * Con: (Depending on design) Could interfere with the muscle-memory for editors of "click the blue-thing after the heading".

Iconography?

 * 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 T18691.)

Discussions on which icon:
 * 1) Section sign: §
 * 2) * Uses: Implementation example at W3C on right side Implementation example at W3C before the heading on the left
 * 3) * 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])." Enwiki's w:en:template:See also automatically converts  into.
 * 4) * Con: In some languages mainly just used in legal context (German, Norway, Polish)  & . In German language, it's nowadays used exclusively in judicial context
 * 5) Link chain icon: 🔗 (unicode) or Link_icon.svg (image)
 * 6) * Uses:
 * 7) * Pro:    &
 * 8) * Con: The link icon is already widely used to set a link in VE, in old wikitext editor surface. Getting a section link is a different action.
 * 9) Bookmark icon: 🔖 (unicode) or Bookmark_icon.svg (image)
 * 10) * Uses:
 * 11) * Pro:
 * 12) * Con: Link chain icon more intuitive
 * 13) Anchor icon: ⚓ (unicode)
 * 14) * Uses:
 * 15) * Pro:
 * 16) * Con: ; Technology-driven metaphor, doubting that most people who haven't been working with HTML directly, are aware of “anchor” metaphor.
 * 17) Number sign: #
 * 18) * Uses:
 * 19) * Pro: Clicking the link will add "#foo" to the URL, so this option is somewhat logical.
 * 20) * Con: Used in wiki markup as number list item. Widely used in connection with hashtags.
 * 21) Paragraph sign/pilcrow: ¶
 * 22) * Uses:
 * 23) * Pro:
 * 24) * Con: We're Not actually linking to individual paragraphs.
 * 25) The section's numbers themselves: 1.2.3
 * 26) * Uses:
 * 27) * Pro: We already have "Auto-number headings" in Special:Preferences (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.
 * 28) * 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.