1307217 - Add "Link to this Paragraph" elements to section headers

Status: RESOLVED FIXED

(developer.mozilla.org Graveyard :: Wiki pages, enhancement, P1)

Description

[John Whitlock [:jwhitlock]]

What problem would this feature solve?
======================================
It is difficult to get a link to a section on an MDN page, which in turn makes it difficult to share specific content.

Who has this problem?
=====================
All visitors to MDN

How do you know that the users identified above have this problem?
==================================================================
I encountered this when trying to share this URL:

https://developer.mozilla.org/en-US/docs/Web/API/WindowTimers/setTimeout#Maximum_delay_value

Once I identified the section I wanted to share, I had to determine the anchor link, which is non-obvious.

How are the users identified above solving this problem now?
============================================================
When I want to share a particular bit of content, my process is:

1) Right-click to "inspect" the element
2) Find the ID of the heading
3) Construct a URL with an anchor link
4) Share the URL

An alternate process is:

1) If possible, resize the browser so that the window is wide enough for the floating table of contents
2) If not possible, memorize the name and scroll to the top of the article
3) Click on the TOC link for the section
4) Confirm you got the right one
5) Share the URL

Do you have any suggestions for solving the problem? Please explain in detail.
==============================================================================
Sphinx / ReadTheDocs adds an anchor link to section headers:

http://django-allauth.readthedocs.io/en/latest/providers.html#github

There is an anchor link inside the heading:

<h2>GitHub<a class="headerlink" href="#github" title="Permalink to this headline">¶</a></h2>

The "headerlink" class:

* Hides the "¶" text under normal circumstances
* Displays it when the mouse hovers over the heading
* Doesn't work on touchscreen devices

We could do something similar for MDN, maybe in the render step so that the links do not appear in the regular content.
Headerlinks 

Is there anything else we should know?
======================================
This is part of the standard Sphinx theme, and does not apply to our Kuma docs with a custom theme.

Comment 1

[Stephanie Hobson [:shobson]]

As a work around you can pick the heading you want to share out of the article table of contents in the right column.

Comment 2

[Stephanie Hobson [:shobson]]

Oh you saw that.

Comment 3

[John Whitlock [:jwhitlock]]

Yes, except it disappears at my normal browser width, so I often forget about it.

This may be an n=1 request, I don't know if anyone else wants to share a particular section.

Comment 4

[John Whitlock [:jwhitlock]]

The Table of Contents has been changed to a "sticky" TOC bar with the H2 headings. The TOC trick can no longer be used except for H2-level heading.

Comment 7

[Eric Shepherd [:sheppy]]

For informational purposes (perhaps to help with later prioritization) --

This came up this afternoon in #content on IRC. smaug and others were commenting on how hard it is to link to specific content on MDN now since we got rid of the TOC. Here's a snippet showing part of the conversation:

4:07:31 PM <jdm> annyG: one option might be to add a `const char*` member to PrefableDisablers indicating the name of the property in question, then modify https://searchfox.org/mozilla-central/source/dom/bindings/Codegen.py#2114 to output the desired string, which might be `member.name` or something?
4:07:59 PM <jdm> qDot might be able to advise; I think they've got some Codegen.py experience
4:37:20 PM <@smaug> https://developer.mozilla.org/en-US/docs/Mozilla/WebIDL_bindings Func=
4:37:33 PM <@smaug> mdn is rather broken for linking
4:38:15 PM <@smaug> sheppy: in the old days there was a nice list of thing on the right
4:38:54 PM <@smaug> sheppy: and if I now manually look at the name of some paragraph, scrolling is wrong, https://developer.mozilla.org/en-US/docs/Mozilla/WebIDL_bindings#Func

Comment 8

[[github robot]]

Commits pushed to master at https://github.com/mozilla/kuma

https://github.com/mozilla/kuma/commit/0155a6c8a9b22e202e4faf5758982a64e1e0e823
Fix Bug 1307217, add link to section elements to improve ux

https://github.com/mozilla/kuma/commit/ab1ed87d73e9f100b9cb2a752da0594bafc7d338
Merge pull request #4901 from schalkneethling/bug1307217-add-link-to-section-elements

Fix Bug 1307217, add link to section elements to improve ux