MDN Web Docs
Replies: 2 comments 4 replies
-
Almost every IDE has preview feature, including GitHub. Why not rely on that? Also, macros are counter productive in such previews as they are not rendered:
At the moment the markdown linter doesn't enforce any line lengths.
To avoid duplication reference style links can be used: ## Get object keys
Function [`Object.keys()`][object.keys] can be used to get all object keys.\
[`keys()`][1] function was added in ES version xyz.\
You can override [`Object.keys()`][1].
## More sections below
...
[1]: /files/en-us/web/javascript/reference/global_objects/keys
[object.keys]: /files/en-us/web/javascript/reference/global_objects/keysThis will be way shorter than macro calls. Also, it'll reduce errors due to copy paste as you need to get only one link correct. Using default language features is more efficient.
I feel the pain. Again reference style links(explained above) can be used. You need to get the link right only once. simplescreenrecorder-2023-03-21_11.30.29.mp4*Ignore html comment style expansions. It is work in progress.
New/non-frequent contributors will still have to refer the macro guide page and go through file hierarchy to craft working macro call. They'll still have to verify it using While working on removing html xref macro we noticed that people guessed page locations in macro calls and didn't bother to verify link validity later. Case for automation
|
Beta Was this translation helpful? Give feedback.
-
That's fair. At the moment xrefs are tied to file/URL structure, but yes, that's because we don't have an organized way of saying what kinds of items are supposed to be xreffable, so our usage rules collapse into their current implementation. In reality I suppose any group of items which share a namespace could be xreffable. This would mean we'd have to:
For instance, if we wanted |
Beta Was this translation helpful? Give feedback.
-
|
This is quite half-baked, but maybe we could start by saying:
Yari could for instance get the set of There are places where page types aren't that helpful: for instance we have different page types for |
Beta Was this translation helpful? Give feedback.
-
This sounds nice as it gives us the freedom of creating any directory hierarchy. If we use it like There are 575 xref macro errors at the moment in No one tries to fix flaws mentioned in PR companion. Having simpler mechanisms is beneficial in the long term. Pure markdown syntax is always easy to maintain. |
Beta Was this translation helpful? Give feedback.
-
But this is already the case, implicitly, with domxref ( Historically I've been team Markdown links, but I think Josh makes good points, and to some extent his post has made me realise that what I really don't like isn't xrefs so much as the random way they are implemented and used in MDN. |
Beta Was this translation helpful? Give feedback.
-
Oh noo, don't switch the team yet! Is it because the ease of use or how the content looks(pretty) using xrefs? Just a thought. How about we, for ease of use, have contributors keep using xref macros but at end of the day or week we run a script to convert |
Beta Was this translation helpful? Give feedback.
-
This is a case of why I hope xref macros would not be removed, and even be encouraged of using. We've recently seen a lot of discussions on why people don't like xrefs and how we want to deprecate them, but IMO their benefits greatly outweigh the complexity.
On moving to Markdown links
There are three reasons why xrefs are better than Markdown links.
Shorter source
Shorter Markdown source has multiple benefits:
Such errors may result from careless copy/pasting. However, the fundamental issue here is that the same piece of information—a link to the
Object.keys()page—is repeated twice, once in the title, once in the URL. If we replace it with{{jsxref("Object.keys()")}}, then there's no duplication altogether, and thus no room for typos.Decoupling from content structure
Whether slug-based or file-location-based, Markdown links inevitably involve typing out the entire path to the target page. This means any relocation of a page requires updating every link to it, which is annoying.
I acknowledge that the current xref implementation is far from ideal. @wbamberg once mentioned that the CSS xref forced the docs to have a flat structure. However, such implementation details should not mask away the underpinning idea of an xref: to abstract away the file system structure. Take a CSS xref for example:
{{cssxref("accent-color")}}. Nothing of its API surface requires a particular file structure, and we can simply re-implement the xref so it does a search among various potential locations for theaccent-colorpage. Fix issues of xrefs by fixing them—not by staying away from them 🙂Ease of authoring
JS links are long, and to this day I don't remember the prefix syntax. Is it
/en-US/docs/Web/? Is it/en-US/Web/docs/? Is it/Reference/or/References/? In the end, the most effective way is to go to the respective page on the website and copy its URL, but that involves switching windows and navigating across pages. On the other hand, using xrefs, all I need is to type out exactly what's on my mind: a link toArray.@OnkarRuikar and @teoli2003 advocated for file-location-based links because of the better editor support. However, this still requires tabbing through every path segment: with a path like
files/en-us/web/javascript/reference/global_objects/array/index.md, that would be 8 tabs, plus some characters to reduce the search space for autocompletion. OTOH, because VS Code also auto-closes braces and parentheses,{{jsxref("Array")}}itself only takes 15 keystrokes, which can be further reduced if one has an editor snippet for{{jsxref("")}}.The idea is to increase information entropy as much as possible. Make every character typed meaningful!
On creating a better xref macro
I can only speak for the jsxref macro in terms of implementation, because I haven't used others as much, but I believe many ideas also apply. There are a few common patterns that lead to the macro not being as ergonomic as it can be:
/-separated segments should never be present in the output. Sometimes, a prefix is necessary to disambiguate—for example,{{jsxref("Operators/in")}}instead of{{jsxref("in")}}, and{{jsxref("Array/map")}} instead of{{jsxref("map")}}. However, this means the rendered text is alsoOperators/in, which makes no sense. A smart xref should recognize that theOperators/part is only present for namespacing, and only renderin, so we don't have to write{{jsxref("Operators/in", "in")}}`.(). Constructors and classes have separate pages—for example,{{jsxref("Array/Array")}}and{{jsxref("Array")}}. In prose, to differentiate them at a glance, we always stylize the former asArray()(with the()). We can take advantage of this and make{{jsxref("Array()")}}automatically expand to{{jsxref("Array/Array")}}. This gets rid of theArray/Arrayduplication.{{jsxref("Statements/async_function")}}and unintentionally introduce the underscores to the output. However, as a matter of fact, we know that the slug can never have spaces, so{{jsxref("Statements/async function")}}should just as unambiguously point to the same page, while not requiring repeating the title a second time for the rendered text argument.{{jsxref("Inheritance and the prototype chain", "Inheritance and the prototype chain", "", 1)}}to{{jsxref("Inheritance and the prototype chain", 1)}}.This makes the xref much more complex, you may say. That's true, but these are complexities that authors will enjoy. What confuses authors the most about xrefs is not their behavior, but the poor documentation. If we can have a dedicated page on the various features of xrefs, I believe authors will soon start to enjoy the awesome experience xrefs bring about.
Beta Was this translation helpful? Give feedback.
All reactions