Replace xref macros with Markdown links

[wbamberg]

Over in mdn/content#13802 , @queengooborg replaced all usages of the {{anch}} macro with Markdown links.

I'd like to propose that we do the same with our xref macros - that is, replace them with plain Markdown links.

What are xref macros?

These are a class of KumaScript macro that create a link, usually within MDN, like {{domxref}} or {{cssxref}} or {{jsxref}}, but sometimes outside MDN, like {{interwiki}} or {{rfc}}. When we did a census of KumaScript macros a few years ago (https://docs.google.com/document/d/1G5KwoJNi8mLmbzcWo-eawH0xw4spVvHGY4Wc4ZEuMYg/edit) we counted 50 of them, making them the second-largest category of macro. They are probably the largest now, since the old largest category of "Internal" has been reduced in the meantime.

Arguments against keeping them

All other things being equal it's always better to use normal Markdown for things rather than macros.

• Contributors can use Markdown links without having to learn special stuff about MDN
• Removing macros simplifies the MDN platform
• Using more plain Markdown makes MDN content more portable
• Our xref macros have inconsistent APIs and even MDN experts have to look up the details. For instance, {{domxref}} takes a fourth argument that will suppress code formatting, while {{cssxref}} AFAIK does not let you suppress code formatting.

Arguments in favour of keeping them

• They automatically add code formatting. This is a genuine benefit most of the time, although we don't always want code formatting: we often see things like {{domxref("Fetch_API")}} which incorrectly code-formats the text. Here the writer needs to do {{domxref("Fetch_API", "Fetch API", "", "something")}} which isn't at all obvious.

• They're quicker to write and easier to read. This is sometimes true. {{domxref("Request")}} looks great. But in many cases it breaks down, especially with docsets that don't have such a simple organization. For example, {{jsxref}} works pretty well for global objects, but:

  • to create a link to for...of you have to do {{jsxref("Statements/for...of", "for...of")}}
  • to create a link to https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await you have to do {{jsxref("Operators/await", "await")}}
  • to create a link to Intl.NumberFormat.format() you have to do {{jsxref("Intl/NumberFormat/format", "Intl.NumberFormat.format()")}}. This is very non-obvious!

[meyerweb]

I’ll add an argument in favor of keeping them: not having to worry about the URL structure of the links, which is nice since the URL structure is often divorced from the directory structure. I used these a lot when doing the Temporal documentation, and having the system auto-link things was very nice. It made find-and-replace of terms with {{jsxref("\1")}} a breeze.

[wbamberg]

One of the things though is that you do (often) still have to worry about URL structure. That's why you have to write things like {{jsxref("Statements/for...of", "for...of")}} - because that page is under "Statements", not "Global_objects".

[teoli2003]

I think there are different cases here: the xref macros that link to outside pages are doing very few things: {{interwiki}} for example is more complicated to use (and rare) so that writers add Markdown links today rather than using it.

{{rfc}} has for only advantage to link to the "right" site: RFCs are available in different formats and this uniformize it. But this goal is not achieved as a lot of RFC links are direct, so I think we can remove it (and update the links). (Can we add a Github test checking for sites that we don't want to link to here? It won't be exhaustive but can likely solve 99% of the cases)

For {{domxref}}, {{cssxref}}, …, they are very convenient for writers as they act as shorthands that are quicker to type and less error-prone. Maybe the solution here is to remove them but to provide an MDN companion add-on for VSCode or other editors to simplify the creation of these links.

[MrBrain295]

@hamishwillee linking within GitHub works but it has to be exactly the same as the actual directory tree (so no /docs and the case needs to be the same).

[hamishwillee]

@MrBrain295 Indeed. My point is right now the format includes /docs etc, so this does not work in github.

[teoli2003]

Note that @hamishwillee would be useful, independently of the removal of the xref macros, and would likely help.

I would avoid allowing ../ though, I think it makes links difficult to read. (I know this is not proposed, but just in case)

[hamishwillee]

@teoli2003 FWIW the big problem with relative links like ../ is that they only work well if you have a very rigid file system structure and you can always predict the indirection. Otherwise you have to think about what indirection you need for every single link, which is something that is hard to review and ensure you got right. So yes, let's avoid that if we can and make it easier for authors.

[Rumyra]

I've gone back and forth with how I feel about keeping or removing xref's - I wanted them because it is easier as an author a lot of the time, however, this is true because I know them... now I consider the 'Arguments against keeping them' - primarily contributor ease of authoring.

I'd love to suggest using markdown link reference format like below so we could perhaps have a succinct format for the links "in-text"

I think a markdown solution could be an interesting approach, but as Hamish says this can prove tricky when it comes to styling.