Requests for comment/Clickable section anchors

This is a request for comment regarding clickable section anchors.

Request for comment (RFC)
Clickable section anchors
Component General
Creation date
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.

Background

edit

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

edit
  • 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. §, ¶, #, , etc, see #Iconography? 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 #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

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 mediawiki.org --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 should happen on-click

edit
  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

edit
  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

Visibility

edit

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

edit

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?

edit
  • 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[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]. In German language, it's nowadays used exclusively in judicial context
  2. Link chain icon: 🔗 (unicode) or (image)
    • Uses: [16][17]
    • Pro: [18] [19] [20] [21] [22] & [23]
    • 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 [24]
  4. Anchor icon: ⚓ (unicode)
    • Uses:
    • Pro: [25]
    • Con: [26]; Technology-driven metaphor, doubting that most people who haven't been working with HTML directly, are aware of “anchor” metaphor.
  5. Number sign: #
    • Uses: [27]
    • 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: [28][29]
    • Pro:
    • Con: We're Not actually linking to individual paragraphs.
  7. The section's numbers themselves: 1.2.3
    • Uses: [30]
    • 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.

References

edit
  1. https://phabricator.wikimedia.org/T18691#1099382
  2. https://phabricator.wikimedia.org/T18691#1098025
  3. https://phabricator.wikimedia.org/T18691#1128358
  4. http://dev.w3.org/csswg/selectors-4/#context
  5. http://docs.python.org/2/library/time.html#time.asctime
  6. https://github.com/jquery/jquery#readme
  7. https://lovdata.no/dokument/NL/lov/1961-05-12-2#§2
  8. https://phabricator.wikimedia.org/T18691#1091293
  9. https://www.w3.org/TR/wai-aria-1.1/#introduction
  10. http://dev.w3.org/csswg/selectors-4/#context
  11. https://phabricator.wikimedia.org/T18691#1127562
  12. https://phabricator.wikimedia.org/T18691#1099382
  13. https://phabricator.wikimedia.org/T18691#1127910
  14. https://phabricator.wikimedia.org/T18691#1127562
  15. https://phabricator.wikimedia.org/T18691#1140399
  16. https://www.mediawiki.org/wiki/MediaWiki:Gadget-vector-headanchor.js
  17. https://github.com/wikimedia/performance-WikimediaDebug#release-process
  18. https://phabricator.wikimedia.org/T18691#1097873
  19. https://phabricator.wikimedia.org/T18691#1140399
  20. https://phabricator.wikimedia.org/T18691#1140415
  21. https://phabricator.wikimedia.org/T18691#1147894
  22. https://phabricator.wikimedia.org/T18691#1147808
  23. https://phabricator.wikimedia.org/T18691#1148154
  24. https://phabricator.wikimedia.org/T18691#1140415
  25. https://phabricator.wikimedia.org/T18691#1230006
  26. https://phabricator.wikimedia.org/T18691#1230338
  27. https://wordpress.org/support/topic/anchor-link-for-ribbon-sections
  28. https://docs.python.org/2/library/time.html#time.accept2dyear
  29. http://www.tbray.org/ongoing/When/200x/2004/05/31/PurpleAgain#p-5
  30. http://tools.ietf.org/html/rfc1345#section-2


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]

Drawbacks:

  • Added complexity next to every header, when we want to draw focus to the [ edit | edit source ] links.


Option 3

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


Pros:

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 [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