[Markdown] Breaking links to fragments

[wbamberg]

In HTML, we can represent heading IDs independently of the heading text. So we can have:

<h2 id="My_heading_id">Something</h2>

We can also of course attach IDs to any kind of element:

<p id="this_paragraph">

Then someone on a different page (or site) can link to https://developer.mozilla.org/en-US/docs/My/Page#My_heading_id or https://developer.mozilla.org/en-US/docs/My/Page#this_paragraph , and get to that part of the page.

In GFM we don't have the ability to support these cases. The only IDs we will have are on headings, and they are always derived from the heading text. So we will break link fragments on non-headings or on heading where the ID is not derived from the heading text.

We can find and fix these cases on MDN itself, but we can't, obviously, do it for external sites.

If this is a showstopper problem, the only option I can see is to support explicitly representing IDs in Markdown (for example, using something like https://about.gitlab.com/handbook/markdown-guide/#classes-ids-and-attributes).

I think this isn't a showstopper, for a couple of reasons:

• although links break in the sense that they don't find the section of the page, it's not catastrophic: they still get to the page and if it still has the relevant content they can probably find what they are looking for.
• we haven't historically cared much about "link fragment compatibility", as opposed to link compatibility. If we move or delete a page, we always consider what should happen to people following the link, and we have a redirects file to help with that. But if we rework a page and retitle (or delete) headings, we don't typically worry about breaking fragments.

But either way I would like us to be clear about this choice :).

cc @escattone , @peterbe (with whom I've talked this over already), @Rumyra , @Elchi3

[teoli2003]

The only link fragments that are not on an Hx that I see having some usefulness are the #attr-xyz on the HTML pages.

E.g. The ping attribute of the a element.

[wbamberg]

These are generally unaffected aren't they, because they're built using {{HTMLAttrDef}}? (https://github.com/mdn/content/blob/main/files/en-us/web/html/element/a/index.html#L77).

It has also occurred to me, while looking at the CSS docs, that we could generate IDs for dt elements, as we do for headings. Not sure it is worth it though.

[teoli2003]

Good point. I forgot about these macros. So we only have to check that all of them are using {{HTMLAttrDef}}, which means checking that no usage of #attr is to create a fragment.

Nice!

[peterbe]

I say; let it break.

You could probably use

-## Old heading
+
+<a name="old_heading"></a>
+
+## New heading

...As a way of making URI#old_heading continue to work even after you change the heading text from "Old heading" to "New heading".

(note: I haven't even tested if that works in our newly landed Markdown)

That would solve the problem with legacy links into that section. Something potentially possible to do for hugely popular links like https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach#polyfill

(note2: I don't know if there are a lot of inbound links to ...forEach#polyfill specifically but it's an example)

[Ryuno-Ki]

I agree insofar, as I'm fine with breaking anchor links, as long as the link text was speaking enough to give me a clue on where I was supposed to land.

[teoli2003]

Sounds doable, rg -l "#attr-" | wc -l returns 52 files to deal with.

[Rumyra]

Sorry if I'm coming to this a bit late

@teoli2003 I've assumed this is the number of files non heading ids affect?

In the past month, these are the top listed urls users have landed on the site direct, which include a fragment:

/en-us/docs/web/api/screen_capture_api/using_screen_capture#result
/en-us/docs/web/html/element/iframe#attributes
/en-us/docs/learn/getting_started_with_the_web/how_the_web_works#clients_and_servers
/en-us/docs/web/api/web_animations_api/using_the_web_animations_api#moving_it_to_javascript
/en-us/docs/web/html/element/img#attr-alt
/en-us/docs/web/http/status#client_error_responses
/en-us/docs/tools/network_monitor/request_details#timings
/en-us/docs/web/api/element#mouse_events
/en-us/docs/web/javascript/guide/expressions_and_operators#expressions

There's 263 results, but the above are all those over 2 users - the top one by far is the screen capture one at the top with 111 using the direct url with id and this is linking directly to an h4.

I'd be inclined to have a guideline which says ids should only be used on headers moving forward (omitting existing macros) and as that's auto with markdown, just no ids. Which in turn concludes -> Not a showstopper 👍

[wbamberg]

Thanks @Rumyra for this data! That makes the issue of external sites linking to pages using fragments seem much smaller.

[hamishwillee]

I'm happy for them to break too, provided the anchor break is reported as a flaw (in linking topics) so we can fix these over time. (@peterbe).

• It would also be really great if we could also have a report of internal links that will be broken if a heading name is change.
• I think we should support option "2" below, even if we don't promote it. Having the option is incredibly useful for cases where you don't want to create a heading but an anchor would still be handy - e.g. linking to a figure.

FWIW There this is how heading anchor persistence is normally handled:

1. Gitbook uses this syntax on headings to indicate a permanent anchor:

   # Heading name {#the_anchor_for_this_heading}
   

   This is not gitbook markdown compatible, but is otherwise an excellent syntax.
2. Otherwise an explicit anchor, usually done with the id rather than name:

   <a id="the_anchor_for_this_heading"></a>
   # Heading name
   

[Ryuno-Ki]

I wonder, what happens to screenreaders in option 2. It's an anchor. Omitting the href makes it not a link (implicit aria role). So if I list all links, it won't show up.

But where would the focus end up with once I jump to it? It has no content, so nothing would be read out, would it?