Allow authors to omit the {{Compat}} and {{Specifications}} macros

[sideshowbarker]

Fixes #6390.

For the normal case where a {{Compat}} or {{Specifications}} macro has no arguments, this change allows authors to completely omit the macro.

That is, this change allows authors to just do the following:

## Specifications

## Browser compatibility

... rather than needing to do this:

## Specifications

{{Specifications}}

## Browser compatibility

{{Compat}}

This change works by directly passing the frontmatter metadata down to the code that builds the contents of the “Browser compatibility” and “Specifications” sections — rather than needing for it to be indirectly passed by the {{Compat}} and {{Specifications}} macros.

This change is also in line with our general de-macro-ization plans — in that it takes us a big step closer to completely eliminating the {{Compat}} and {{Specifications}} macros.

---

Part of the context for this change is that #5347 (reply in thread) has persuaded me that it would be a good idea for us to move wholly over to just using the browser-compat and spec-urls macros, and never using the {{Specifications}} and `{{Compat}} macros.

The specific parts of #5347 (reply in thread) I found persuasive were:

Macros with arguments

...
…my preferences are toward:

1. Providing fewer ways to author things. Either the key is the only way it's done, or there ought be more unified way of richly citing/embedding non-MDN content.
2. Not committing to Kumascript-isms in Markdown.

In general, I'd really like to get away from macros as a way of embedding stuff in Markdown and it didn't feel like it was in scope for this discussion. That said, I'd like us to explore alternatives to Kumascript macro syntax, particularly the bits that are most unlike Markdown (in this case, arguments).

[caugner]

Would it be a viable alternative to just omit those headings altogether, and to automatically add two sections "Specifications" and "Browser compatibility" at the end , if the document contains spec-urls and browser-compat in its frontmatter, but no corresponding macro in its body?

(I'm also asking because the approach in this PR does not work for translated-content.)

[sideshowbarker]

Would it be a viable alternative to just omit those headings altogether, and to automatically add two sections "Specifications" and "Browser compatibility" at the end , if the document contains spec-urls and browser-compat in its frontmatter, but no corresponding macro in its body?

Seems to me it could be viable — I can’t personally think of anything specific that would prevent it — but I also seem to recall that in previous discussions about the possibility of doing that, @Elchi3 may have given some reasons why it wouldn’t work.

[Elchi3]

It could work. Note that "See also" is often the last section, so a rule that says "Specifications and Browser compatibility always at the end" isn't it in all cases. Also, there might be other sections that might get in the way, so maybe having the headings is more reliable? That said, if you figure out a way how to do insert the two sections at the correct place without any kind of marker, then sure, add it it automatically at the correct position.

A drawback here is that writers need to work with this automatic insertion and loose some freedom when outlining a page. However, we probably don't want that freedom so much since we rather want to have more consistent reference pages 🤷

[sideshowbarker]

A drawback here is that writers need to work with this automatic insertion and loose some freedom when outlining a page. However, we probably don't want that freedom so much since we rather want to have more consistent reference pages 🤷

That’s a really good point. That leads me to think that from a reader user-experience point of view, giving authors the freedom to drop Specifications and Browser compatibility tables into arbitrary places in documents is not at all a win for readers. It seems inherently disruptive for readers.

What I mean is, as used in their normal placement in reference documents, the Specifications and Browser compatibility tables don’t require any introductory text — because for readers they take their meaning from the structure.

But if an author puts a Specifications and Browser compatibility table in some surprising place that’s inconsistent with how all the rest of the docs are structured, then how’s a reader supposed to understand why that table’s showing up in an odd/unexpected place?

I guess in such cases the table could be preceded by a some introductory text to explain the context — but at that point, as a reader, I’d wonder why the document isn’t just providing a link to the relevant specification or compat data within a sentence in a normal paragraph in the body of the article. I can’t imagine what value having the spec link or compat-data link popped out into a table brings to me as a reader of the article. It would just seem disruptive.

For the same reason, I can’t see now why we want to allow authors to have the freedom to place Specifications and Browser compatibility tables into non-reference articles at all. In non-reference docs, I can’t see how the tables would end up being anything but disruptive in the normal flow of the articles, and bad for the user experience of readers.

[caugner]

Thank you @Elchi3 and @sideshowbarker for sharing your thoughts on this.

I think this change would only really make sense if the {{Compat}} and {{Specifications}} macros were actually be deprecated at the same time. This, in turn, would require translated-content to be taken into account as well as those sections that commonly appear after Compat/Specifications.

Identifying those sections would be a good next step, and moving the "See also" links to the frontmatter (and adding a {{SeeAlso}} macro for this temporarily) might be the way forward.

[wbamberg]

I'm a bit uncomfortable with things like "the ordering and placement of BCD and spec tables" being hardcoded deep inside some Yari magic.

When we were working on stumptown we did something similar to this, but we had page templates (that we called recipes) that defined the order of sections for different types of pages. So there was some human-readable (and editable) specification for the page structure, that governed the way the platform put pages together.

I can’t see now why we want to allow authors to have the freedom to place Specifications and Browser compatibility tables into non-reference articles at all.

Yeah, I agree with this. We do it at the moment though, so there is some cleanup there.

[github-actions]

This pull request has merge conflicts that must be resolved before we can merge this.

[caugner]

Sorry, this needs a proper (non-trivial) rebase because of #7612.

[wbamberg]

per #5971 (comment) although I like the general idea here I'd like a more explicit/semantic way of attaching these sections to pages, so I would be happy to close this PR.