Page MenuHomePhabricator

RFC: Section header "share" link
Open, MediumPublic

Assigned To
None
Authored By
brion
Dec 17 2008, 6:36 PM
Referenced Files
F31912931: image.png
Jul 1 2020, 4:46 PM
F30391049: image.png
Sep 18 2019, 8:34 PM
F29873862: image.png
Jul 25 2019, 11:37 PM
F29534961: image.png
Jun 14 2019, 12:04 PM
F29322365: image.png
Jun 3 2019, 12:18 AM
F29289197: image.png
May 31 2019, 10:07 PM
F29285588: Screen Shot 2019-05-31 at 10.55.42 AM.png
May 31 2019, 6:00 PM
F29280626: image.png
May 30 2019, 4:41 PM
Tokens
"Like" token, awarded by Prototyperspective."Like" token, awarded by Thgoiter."Yellow Medal" token, awarded by Demian."Love" token, awarded by MusikAnimal."Like" token, awarded by Trizek."Love" token, awarded by Quiddity."Like" token, awarded by nray."Love" token, awarded by Niedzielski."Burninate" token, awarded by osorio-juan-microsoft."Love" token, awarded by Sebastian_Berlin-WMSE."Like" token, awarded by Liuxinyu970226."Love" token, awarded by eflyjason."Love" token, awarded by Kaartic."Love" token, awarded by Niharika."Like" token, awarded by Pcoombe."Like" token, awarded by Ciencia_Al_Poder."Like" token, awarded by He7d3r."Dislike" token, awarded by Jooojay."Like" token, awarded by waldyrious."Like" token, awarded by gpaumier."Like" token, awarded by Arghman."Like" token, awarded by fbstj."Mountain of Wealth" token, awarded by Nemo_bis.

Description

  • Affected components:
    • MediaWiki core Parser (Parser output and cache)
    • MediaWiki Skin system
  • Engineer for initial implementation: @osorio-juan-microsoft
  • Code steward: TBD.

Motivation

Today, it is hard to share links to sections of wiki pages. Sections on a page don’t have a link to themselves on the page, except at the top of the page in the Table of Contents. If the page is long, a reader would have to scroll all the way to the top to copy the link and remember the name of the section they wanted to share.

This RFC aims to make it easier for readers to share links to sections on wiki pages. Both for "external" purposes (full URL to the section) and "internal" links (to use as internal link from another page in VisualEditor or in a wikitext editor).

Requirements
  • Accessibility: The section section share link read should not be read aloud by screen readers as part of the heading text when iterating through the headings on a page.
  • Internationalization: The section share link should work for both left-to-right and right-to-left layouts.
  • Headings that are produced by <h2> syntax in wikitext currently do not have utility links like "edit section". The section share link should also not be added to these (T91271).

Exploration

Related ideas:

Status quo

There are a number of workarounds that already provide the basic functionality on some wikis through gadgets and user scripts:

Proposal 1

Clickable section anchors, in the form of an § icon next to page heading, were implemented and briefly deployed in March 2015.

Code:

Screenshot
pasted_file (253×213 px, 9 KB)

This has since been reverted from MediaWiki core and un-deployed from WMF wikis. There were numerous problems that can be found in detail at T18691#1051560, T18691#1098570 and other comments after it. Including:

  • The CSS was not compatible with an RTL layout.
  • The space for the element was not consistently reserved for the layout box (e.g. partially "hanging out" if the heading is inside another element) – T18691#1073006
  • The meaning of the icon it used was not clear to some users. – T18691#1097797, T18691#1097768
    • It was mentioned that making the symbol localisable might be enough to address this. Others mentioned that using a symbol relating to "anchors" and "linking" might work universally (instead of an icon relating to "sections" or "paragraphs"). – T18691#1098570
  • The element was not excluded for <h2>-syntax headings.
  • The element could not easily be disabled for some headings, such as on the Main Page. It was thought this could be resolved by applying a CSS class to the HTML element, so that it can be hidden by CSS override.
  • The element was visible by default, which was thought to be distracting or "crowded" by some.
    • It was mentioned we could or should perhaps hide it by default and show it after a certain interaction with the heading or section, e.g. hover/focus on desktop (for mouse, keyboard navigation, and assistive technology). Mobile UX has not yet been proposed.

Other variations of this proposal were originally documented on mediawiki.org, at https://www.mediawiki.org/wiki/Requests_for_comment/Clickable_section_anchors.

Proposal 2

This is the solution we currently want to get approved and merged.

  • A “share” link will be added to the existing “edit” or “edit | edit source” widget.
  • This applies to all MediaWiki heading classes, that currently has the edit link widget.
  • But this will not apply to literal headings (when users use HTML header tags directly, such as <h1>, <h2>, <h3>…)
  • This “share” link is a clickable link.
  • When the user clicks on this “share” link, a window pops up that allows both sharing internally with wikitext and externally with full URL.
  • This solution works for both left-to-right and right-to-left layouts.

The implementation looks like this:

image.png (208×398 px, 48 KB)

Related Objects

Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes

I agree that the consideration of making "N" utility links spoken or not by default when reading an article is a separate task. However, I think it's important to consider that we don't have N utility links today. Historically (and for most pages for most users, still) there is 1 link, the primary action we invite users to do: Edit. The transition to having "a group of utility links", in a way that is visible to most users, starts with this RFC.

The question becomes: When scanning an article through assistive technology, what should the experience be? Should they hear by default in unskippable fashion: "Name of person, Biography, Link edit section, Link share this section, (text of biography), Early life, Link edit section, Link share this section, (text about early life), See also, Link edit section, Link share this section (list of other articles)".

I don't know the answer to that. I also don't know what the alternative is, or how other (greatly accessible) web apps tend to deal with the use case of providing inline actions about a paragraph in context with reading.

This is a great question! I don't specialize in accessibility, so I also would love to hear input from someone with more experience in this field :)

Ok, so, good progress here. The technical committee would like to see concerns from the March 2015 version reviewed, to ensure we don't repeat any of those problems. As stated in the description, the issues were raised in and around comments T18691#1051560 and T18691#1098570, and include:

  • The CSS was not compatible with an RTL layout.
  • The space for the element was not consistently reserved for the layout box (e.g. partially "hanging out" if the heading is inside another element) – T18691#1073006
  • The meaning of the icon it used was not clear to some users. – T18691#1097797, T18691#1097768
    • It was mentioned that making the symbol localisable might be enough to address this. Others mentioned that using a symbol relating to "anchors" and "linking" might work universally (instead of an icon relating to "sections" or "paragraphs"). – T18691#1098570
  • The element was not excluded for <h2>-syntax headings.
  • The element could not easily be disabled for some headings, such as on the Main Page. It was thought this could be resolved by applying a CSS class to the HTML element, so that it can be hidden by CSS override.
  • The element was visible by default, which was thought to be distracting or "crowded" by some.
    • It was mentioned we could or should perhaps hide it by default and show it after a certain interaction with the heading or section, e.g. hover/focus on desktop (for mouse, keyboard navigation, and assistive technology). Mobile UX has not yet been proposed.
  • Accessibility issue raised by Timo above: T18691#5547922

I would like to assign stakeholders to go over these and also read through the original task comments that raised them. I'm thinking @ovasileva can help coordinate a review of the technical concerns and @Volker_E can help coordinate a review of the design concerns, especially the accessibility. If I guessed wrong, ping me and we'll try to find someone else. Ideally the feedback would be incorporated in the RFC (task description), and I can help with that.

New design has a few benefits over the old (icon based) design. I'll try to address all the points.

Ok, so, good progress here. The technical committee would like to see concerns from the March 2015 version reviewed, to ensure we don't repeat any of those problems. As stated in the description, the issues were raised in and around comments T18691#1051560 and T18691#1098570, and include:

  • The CSS was not compatible with an RTL layout.

Current solution is RTL-compatible (feel free to verify).

  • The space for the element was not consistently reserved for the layout box (e.g. partially "hanging out" if the heading is inside another element) – T18691#1073006

Current design extends on the "edit" link section and thus doesn't have this style issue.

Current design does not use an icon.

  • It was mentioned that making the symbol localisable might be enough to address this. Others mentioned that using a symbol relating to "anchors" and "linking" might work universally (instead of an icon relating to "sections" or "paragraphs"). – T18691#1098570

Symbol not used anymore. localisable text "share" used instead.

  • The element was not excluded for <h2>-syntax headings.

<h2>-syntax headings do not have the "share" link, as expected.

  • The element could not easily be disabled for some headings, such as on the Main Page. It was thought this could be resolved by applying a CSS class to the HTML element, so that it can be hidden by CSS override.

Current design respects the NOEDITSECTION magic word

  • The element was visible by default, which was thought to be distracting or "crowded" by some.
    • It was mentioned we could or should perhaps hide it by default and show it after a certain interaction with the heading or section, e.g. hover/focus on desktop (for mouse, keyboard navigation, and assistive technology). Mobile UX has not yet been proposed.

Still visible by default. In my opinion, current design is less intrusive.

Need to explore this one

I'm a screen reader user who commented waaaaaay above. If a link *had* to be added, adding it after the "edit" link would be best. However screen readers will generally read the link text, not the title, unless instructed otherwise, so they'd here, for example, "Early life edit share". I for one think an edit link is relatively straightforward, but a share link would be confusing ... the average user would be thinking "share what? With whom? How? The same would apply to a lesser extent with "Share this section", but that's more words. I don't know about anybody else, but I would use this rarely enough that I would disable it immediately if it was ever enabled by default on Wikimedia wikis.

I was planning to log a feature request ticket, but found that this task already exists. For what it’s worth here is my user story:

As an editor and collaborator, I would like an easy way to copy the wikilink for a section to paste into an article or talk page. As a reader I might also want to copy the URL to paste elsewhere.

My point is that collaboration is a big part of this. Also linking to help or policy sections. As Quiddity wrote:

As a Wikipedia editor, I frequently need to link to subsections of discussion pages, and of policy/guideline pages, …
… frustation of having to copy & paste from the page-title and subsection independently (or remove the underscores from the URL).

This task looks pretty mature, and a lot of decisions are already committed. A few extra thoughts anyway:

  • Hover versus always-visible: please don’t make it hover-only. Some people use the desktop site on touch devices. Structured Discussions has some good elements that toggle state on tap as well as hover, though that behaviour isn’t very discoverable.
  • Heading level. If a page doesn’t have level-4 headings, then it’s not going to have level-4 sharing either. It’s not deep subheadings that cause clutter, but short sections.
  • On-by-default and user preference. Personally, I would like to see this default-on for all Wikimedia wikis, with per-user opt-out. It would benefit non-logged-in users. But the language communities being what they are, we should allow each one to hold their own RFC. Turn it on for Beta and MediaWiki wiki as soon as available, to showcase the feature and let people see it in action. In case English Wikipedia says “no”, can I have a user preference to turn it on for myself, please? (In other words, deploy as user opt-in, then let each wiki community choose to flip it to opt-out.) Could it be promoted with a banner or a one-time popover, or is that too intrusive? (I only learned about AMC because of the popover.) Let’s not have another MediaViewer SuperProtect incident so soon after FramBan (and similar SanFranBans that happened on DE and ZH).
  • Mobile site. Please don’t leave mobile in the too-hard basket. This would benefit non-AMC users too. A link icon next to the pencil would be great.
  • Skins. Will skins like Timeless need to be modified to work with section sharing? I gather @Isarra has been very busy, hope it won’t be much work.
  • Permalinks. I’d love to have a permalink option for both the URL and wikilink (using Special:Permalink for the latter). Four text fields may be too cluttered. How about a selector to switch between standard and permanent forms?

@Pelagic As a workaround--and to be able to copy anchors from other sites, my add-on (Firefox or Chrome) might help: https://github.com/brettz9/jump-to-anchor#jump-to-anchor

@osorio-juan-microsoft you are planning to look into the screenreader issue on your side? Thanks!

@osorio-juan-microsoft you are planning to look into the screenreader issue on your side? Thanks!

I think in technical terms the solution isn't too challenging (I would just add aria-hidden labels to the link elements in order to have screen readers skip them).

However, I think that's a bigger discussion to be had. Whether or not the links are read (or which ones are specifically), as well as what kind of text is read ('share' vs. 'share this section', etc), is way beyond my scope.

Please make sure not to add aria-hidden to focusable elements without removing focus, see:
https://dequeuniversity.com/rules/axe/3.3/aria-hidden-focus

Historically (and for most pages for most users, still) there is 1 link, the primary action we invite users to do: Edit. The transition to having "a group of utility links", in a way that is visible to most users, starts with this RFC.

On most wikis, not counting English Wikipedia, there are two links: ‘Edit’ and ‘Edit source’. In fact, it is kind of strange that all the design proposals are seeing how it looks just with ‘Edit | Share’, not considering how it would look, for example, with text ‘Bearbeiten | Quelltext bearbeiten | Teilen’ or ‘править | править код | поделиться’.

Hi,
It's a very interesting conversation. It reminds me https://phabricator.wikimedia.org/T183747
Maybe they could be related?

If the page is long, a reader would have to scroll all the way to the top to copy the link and remember the name of the section they wanted to share.

A radical proposal: Instead of a "share" link, have a "TOC" link that links to the relvant line in the TOC (rather like links from citations to where the citation lies in the body text).

For Chinese wiki, we have at least 2 conversions: traditional Chinese and simplified Chinese. Till now, the section anchor only works on exactly the same characters of the section title. I think it will be a good idea to let the section link also works on different conversions. However, it maybe needs a new design.

If the page is long, a reader would have to scroll all the way to the top to copy the link and remember the name of the section they wanted to share.

A radical proposal: Instead of a "share" link, have a "TOC" link that links to the relvant line in the TOC (rather like links from citations to where the citation lies in the body text).

Unfortunately, that wouldn't solve the two issues of

In T18691#5550415, Pelagic wrote:

...

  • Permalinks. I’d love to have a permalink option for both the URL and wikilink (using Special:Permalink for the latter). Four text fields may be too cluttered. How about a selector to switch between standard and permanent forms?

👍

I currently use User:The Earwig/permalink.js extensively for this. It creates a wikilink with Special:Permalink, which is great, but I often need to change it to full URL which can be tedious (underscores instead of spaces, etc.). There is a "Permanent link" option under "Tools" in native MW, but you of course still need to manually append the section title.

Also, I should note that it's super common for people link to live discussions without using a permalink, so the link can quickly become broken after the discussion is archived or renamed, etc. If there's a native way to easily get permalinks, people will eventually learn to use them, and save the follower of those links a lot of time. It's very un-fun trying to dig through archives and revision histories to just find the discussion.

In T18691#5585283, @MusikAnimal wrote:
[...]
If there's a native way to easily get permalinks, people will eventually learn to use them, and save the follower of those links a lot of time. It's very un-fun trying to dig through archives and revision histories to just find the discussion.

Yes! This is a great point. I agree that we should include the ability to generate permalinks.

Let me know if you need any review specifically from Reading web team by re-adding the tag.

It looks like one of the subtasks of this task has been marked as stalled. Should this task be marked stalled too? It looks like excellent discourse is happening but it's not quite clear to me if everyone is in agreement as to what the status of this RFC is or what's required to move forward that isn't already furnished. I hope this doesn't come off wrong but I wondered if maybe there's a bit of perfect is the enemy of good given the workarounds cited in the status quo. 👍

The workarounds cited in the status quo have the benefit of having no singificant impact on core's API stability, prod infrastructure, caching etc. They also have the benefit of being able to completely ignore all aspects in which they make accessibility, usability or localisation worse because they are opt-in and self-selected.

If there is a minimal version of this that product designers/managers can internally agree on, and that allows the additional features to be added in future iterations – within the same technical basis, then I think we have a pretty good way to move this RFC forward.

We have tried this multiple times in gadgets and even in core, and I think it's pretty clear that the issues that remain unanswered in this task are not things we can "fix" later on, as they have repeatedly led us to have to rethink the implementation from the ground up. If these issues are considered unimportant and acceptable to never be implemented, then I encourage the product lead for this to state so and remove them from the acceptance criteria which would in turn liberate engineers to come up with a simpler solution that we can move forward.

I'm a big fan of moving this RFC forward... On our end, we have internally deployed the solution described in Proposal 2. Usage stats is surely suggesting that internal customers find it VERY useful.

Krinkle moved this task from P2: Resource to P3: Explore on the TechCom-RFC board.

From my perspective the code looks good and is delivering value. It is also behind a feature flag which defaults to false.

I'd rather not block the efforts and needs of 3rd parties here and move forward with it as is. In future, as a next step I could see us making this configurable as a user preference while we figure out how to apply it to the Wikimedia product. This seems a useful feature that we can iterate on.

Is there any problem with us doing that? cc @Niedzielski @Krinkle

From my perspective the code looks good and is delivering value. It is also behind a feature flag which defaults to false.

[…] I could see us making this configurable as a user preference while we figure out how to apply it to the Wikimedia product. This seems a useful feature that we can iterate on.

The various stakeholders have given lots of input. Please process this input and indicate which things are already addressed, which things are considered non-essential to you, and which things can be done later instead. For the things that can be done later, I think is important to somewhat plan ahead and reassure TechCom and others here that those things actually can be done later in a way that isn't a breaking change. See my previous comment:

If there is a minimal version of this that product designers/managers can internally agree on, and that allows the additional features to be added in future iterations – within the same technical basis, then I think we have a pretty good way to move this RFC forward.

We have tried this multiple times in gadgets and even in core, and I think it's pretty clear that the issues that remain unanswered in this task are not things we can "fix" later on, […]

If making it work for WMF is likely to require a breaking change, then I think what you're asking for is to ship the MVP as an experimental/unofficial feature (outside the RFC track), with the knowledge that it may change or be removed any time. We'd then leave this RFC open to track doing it for MW by default and for Wikimedia wikis, which is what this RFC is for.

As far as I'm concerned, there is no need for an RFC to ship an experimental feature to third-parties if its impact on core overall is well-contained.

For the things that can be done later, I think is important to somewhat plan ahead and reassure TechCom and others here that those things actually can be done later in a way that isn't a breaking change.

Okay I'll defer to @ovasileva / product here then as I can't answer that question.

Sorry for the late reply here. The current implementation is approved from our side, in terms of both product and design. That said, deploying to production would probably take some time - we'd have to consult with communities and make sure the change is accepted overall, we'd also have to do some detailed QA across projects and identify which projects this makes sense going out to. I think that's where the feature flag @Jdlrobson mentioned plays in. From our side, MVP is okay, but we still have to do some due diligence prior to deployment and, as we're currently focused on desktop improvements, it might take us a bit of time before we get to it.

@Krinkle is there a clear point person/team for who will review https://gerrit.wikimedia.org/r/#/c/mediawiki/core/+/513234/
Given it touches the parser output, I'd be keen for the parser team to own the review/merging of the core patch. Once it's in per @ovasileva we can arrange rollout. I'd really like to see this move forward in some way.

@Jdlrobson I don't see my concerns/questions from T18691#6033238 addressed. I think that's needed before we can move forward with the RFC, let alone its implementation or rollout.

Generally relevant: on Hindi Wikipedia there is a share feature located next to the article title

image.png (542×737 px, 231 KB)

It should be noted that while these work:

the following does not work nor refer to the same thing:

but rather one has to use something like:

I realize URL fragments are handled in the client-side browser and although it is possible to have "action=view" support a "section" causing a redirect to the correct fragment, this is probably a poor idea as adding any intermediate heading would then break these links. This is precisely why edit links should not be bookmarked (and why adding "section" to "action=view" is not useful).

I bring this up because the edit links are stylized in a certain way and proposal 2 wants to add to these but the semantics are completely different (and why I liked proposal 1 better—despite its other issues that caused it to be rejected).

And while we are on the subject, there is also the issue of how to share anchor links that are not subject headings. Will this code also provide for that. I know many Wikipedia pages that have sections that have changed names many times (often with longer descriptive headings) but they also have succinct anchors to the sections allowing links that change considerably more slowly. Redirects often used these anchors instead of the section names.

If we are going to encourage external links to sections, I recommend we also encourage external links to editor created anchors (e.g., those created via Module:Anchor or Template:Anchor ).

If we are going to encourage external links to sections, I recommend we also encourage external links to editor created anchors (e.g., those created via Module:Anchor or Template:Anchor ).

That doesn't seem feasible, and it's outside of the scope of this task

That doesn't seem feasible, and it's outside of the scope of this task

I never suggested such was feasible or in scope, however, I do think it deserves a discussion point as the reason for wanting such external linking is actually even larger for editor created anchors than for sections. As such, they help define the problem here and possible arguments for or against the proposals here.

This is important and would be very useful. Could you please add this asap?

I can't believe this has been proposed in 2008 but still hasn't been implemented – if there are some unsolved caveats and issues with it, why don't you add a simple preliminary version of it now right away? Any minor problems can still get solved later, at least the user then have this basic functionality.

Currently, most similar websites have such a feature. I support Proposal #1 which is what I'm referring to here. To see how it can look like see this example (hover over or tap-and-hold the section header and see the § on its right or left) or any Github readme.

This would be especially useful needed on mobile where one doesn't have a TOC. If one wants to share a section link on mobile (most readers), which is very useful and common, one has to (most readers on mobile don't know this):

  1. make the mobile Web browser show the desktop version of the page and then
  2. manually remove the m. from the url and
  3. press-hold the very small section header in the TOC to copy the link

Currently, most similar websites have such a feature. I support Proposal #1 which is what I'm referring to here. To see how it can look like see this example (hover over the section header and see the § on its right or left).

How do you hover on mobile? Which design do you expect for Proposal #1 from mobile devices?

Press-and-hold tapping as described in step 3; edited.
A § appearing next to the section header that you can press and hold to copy the link (preferably on the left). This is implemented (since quite a few years) for readmes (markup language) on GitHub.

“tap-and-hold” may trigger other actions depending on browsers (e.g. contextual menu, text selection…)
GitHub uses @media (hover: none) .icon { visibility: visible !important; } to ever show icons which are only showed while hovering on desktop.

1 - Note: I noticed there's a new extension which relates to this task. It does not solve it, but is of interest.
It doesn't help us, because it has a built-in feature that makes Clicking the link immediately copy it to our clipboard, which I know is not wanted by many people (because it unexpectedly overwrites whatever was currently in our clipboard).
Basic docs: https://www.mediawiki.org/wiki/Extension:SectionAnchors
And more details on the 3-types of click (click, ctrl+click, and ctrl+shift+click) feature, at https://en.wiki.bluespice.com/wiki/Reference:SectionAnchors#Features

2 - @Prototyperspective We tried a simple version in 2015, but there were significant problems and edge-cases (summarized in the Description under proposal#1), plus some people strongly dislike any moving/changing-elements in a webpage as they scroll so there were widespread complaints.

3 - Relatedly, I've now overhauled the "Open questions" section in the wikipage ( https://www.mediawiki.org/wiki/Requests_for_comment/Clickable_section_anchors#Open_questions ), and that's probably the best place to record all objective details about the options and their pros/cons, rather than here where they get scattered (and emails are sent to ~100 people each time).
Hope that helps!

@Pols12 Yes exactly, what I referred to is how to make the context menu show up on mobile where one can then copy the link. On Github readme this is also on mobile, if you test this. Maybe one can make the section link get copied automatically when one press-holds the section header on mobile but I meant showing the context menu of the section link.
Note that all of this should also be possible in the mobile app, not just in mobile Web browsers.

@Quiddity 1. Great but even stranger that it hasn't been implemented by now: maybe you could just use that extension code.

  1. These problems can get solved or if too complex get solved after it's rolled out due to being minor. "The element was visible by default" is an understandable major problem but I suggested the § is only shown at hover (you could even require a 1 second hover) just like most websites have it by now. There will always be some niche largely unjustified complaints even for the best, most needed, externally widely established (e.g. GitHub), community-wise heavily supported changes.
  2. That is linked only as "Other variations of this proposal..." above. For deliberating, voting on and aggregating Pro/Cons of options, Kialo can be very useful at some point but currently requires users here to sign up first rather than logging in with Wikipedia credentials.

This would be especially useful needed on mobile where one doesn't have a TOC.

This is a very sensible petition.

With the collapsible sections of MobileFrontend, it may help if uncollapsing a section, the anchor gets added to the URL automatically (without affecting scroll). There's a JavaScript api for that implemented by browsers, that also doesn't add entries to the browser history. It can also update the anchor in the URL automatically when scrolling, to the section heading placed at the top of the viewport. However, this has the problem that, sometimes readers won't want to link to a specific anchor, or the correct anchor is not correctly guessed.