Requests for comment/Clickable section anchors

Tracked in Phabricator
Task T18691

Request for comment (RFC)

Clickable section anchors
Component	General
Creation date	5 December 2012
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) See Phabricator.

This is a request for comment regarding clickable section anchors.

Background

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.

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 #Iconography? below)

  Header

Header  ¶

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 #Iconography? 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?

Open questions

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)?
   • Pro: This is the outcome in most external usages of this concept.
2. Copy [something] to clipboard? (see section below)
   • 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).
   • Note: The new-in-2023 Extension:SectionAnchors has 3 auto-copy features (click, ctrl+click, shift+ctrl+click) documented at their site.
3. Open a popup-modal-window with options?
   • Pro: The desired option per Proposal #2 in phab:T18691.
   • Pro: Provides a logical location for the other regularly-requested feature of direct platform-share links, cf. m:Social media plugins and most of the links there.

What to share/copy

1. wikilink
   • e.g. Page title#Heading words with spaces
   • 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.
2. ID
   • e.g. #Heading words with spaces
   • Con: Not as commonly needed by editors, and would significantly enlarge any options window.
3. href
   • e.g. https://www.mediawiki.org/wiki/Page_title#Heading_words_with_underscores
   • Pro: To accomplish possibly broadest usage (i.e. social media sharing) a full URL seems advantageous.
4. Permanent link
   • e.g. https://www.mediawiki.org/w/index.php?title=Requests_for_comment/Clickable_section_anchors&oldid=2425851
   • 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
   • e.g. Special:MyLanguage/Page title#Heading words with spaces
2. href
   • e.g. https://www.mediawiki.org/wiki/Special:MyLanguage/Page_title#Heading_words_with_underscores
   • 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)
   • Con: Frustrates some readers/editors who dislike the distracting appearance/disappearance as they scroll.
   • Pro: Less visual noise during normal reading.
   • Pro: Commonly used in external implementations.
2. If always visible, how strong?
   • Note: Intended patch, which targeted to decrease contrast. Must take into account color contrast requirements!
   • Pro: Removes the animation frustration issue.
   • Pro: Consistent for touch-screen users.

Location

Should it be located:

1. Before the heading?
   • Pro: Reduces interference with existing location of [edit] links.
2. After the heading?
   • Pro: Reduces the edge-cases for headings within box-designs which can cause the anchor-link to overlap with the border.
3. After the [edit] link(s)?
   • Pro: Logically a part of an 'interaction'.
   • 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 phab:T18691#1097802.)

Discussions on which icon:

1. Section sign: §
   • Uses: Implementation example at W3C on right side
     Implementation example at W3C before the heading on the left
   • 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 § .
   • Con: In some languages mainly just used in legal context (German, Norway, Polish) & . In German language, it's nowadays used exclusively in judicial context
2. Link chain icon: 🔗 (unicode) or (image)
   • Uses:
   • Pro: &
   • 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.
3. Bookmark icon: 🔖 (unicode) or (image)
   • Uses:
   • Pro:
   • Con: Link chain icon more intuitive
4. Anchor icon: ⚓ (unicode)
   • Uses:
   • Pro:
   • Con: ; Technology-driven metaphor, doubting that most people who haven't been working with HTML directly, are aware of “anchor” metaphor.
5. Number sign: #
   • Uses:
   • 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.
6. Paragraph sign/pilcrow: ¶
   • Uses:
   • Pro:
   • Con: We're Not actually linking to individual paragraphs.
7. The section's numbers themselves: 1.2.3
   • Uses:
   • 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

Option 1

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

Header

Header

Drawbacks:

• 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)

Option 3

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

Header

Pros:

• Having an a id="" seems not to affect VoiceOver. It reads it as normal heading. See http://s.codepen.io/Volker_E/debug/KzmQQL --VEckl (WMF) (talk) 08:23, 24 March 2016 (UTC)

Drawbacks:

• 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

Header

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