Support browser_compatibility as a front matter key

[wbamberg]

(and make it available to KS. Actually, make all of front matter available to KS).

Like:

browser_compatibility: css.properties.margin

At the moment compat tables are built something like:

• authors include the {{ Compat }} macro, passing it a BCD query like "css.properties.margin"
• the {{ Compat }} macro emits a <div class="bc-data"> with an id set to that query
• some magic Yari code, when it finds a <div> like that, fetches the BCD query value from the id and uses it to construct a table

Just semantically, I think it would be better to have the BCD query in front matter than as an argument to the {{ Compat }} macro. Then it just represents an extra bit of data to associate with this thing, and the only thing {{ Compat }} is doing is telling Yari where in the page to put the table. And if we ever have machine-readable page types (aka recipes), we don't need that either, because a common page type would include that location information.

But! BCD can be used for more than just the compat tables. There's a project to include spec URLs in BCD, and use a KS macro to add the spec tables, based on the BCD query (mdn/content#1146). If the BCD query is in front matter, then compat and spec tables can be driven from that one data item.

Also, BCD indicates when features are "deprecated": elsewhere we've discussed using this to power "This feature is deprecated" warnings in pages. If BCD is in front matter, then this feature can also be driven by the same data item.

Also, we've talked in the past about having a sort of "BCD summary" thing at the tops of pages, to flag compat issues. Same thing: if BCD is in the front matter we can use it to drive that, too.

---

For the first attempt it would be helpful to make this front matter item accessible to KS. Then for now, the platform code that finds the <div class="bc-data"> doesn't need to change, we could just adjust {{ Compat }} to use the front matter instead of an argument. Ideally I think KS macros should just get access to all front matter values. But eventually we could change things so {{ Compat }} is just not aware of the BCD query at all, in the common case.

We would still need to support a BCD query argument to {{ Compat }}, because some pages contain more than one compat table. But this I think is pretty unusual. So we would make the argument optional (and omit it in 95% of cases).

[peterbe]

So instead of:

---
title: Title
slug: slug
---

<h2>Browser Compat</h2>
{{Compat('css.properties.margin')}}

<h2>Other notes</h2>
<p>Also check out:</p>
{{Compat('css.properties.margin_right')}}

it's supposed to become:

---
title: Title
slug: slug
browser_compatibility: css.properties.margin
---

<h2>Browser Compat</h2>
{{Compat()}}

<h2>Other notes</h2>
<p>Also check out:</p>
{{Compat('css.properties.margin_right')}}

And inside Compat.ejs something like this:

-var query = $0;
+var query = $0 || env.metadata.browser_compatibility;
+if (!query) {
+  throw new Error("Compat macro called without query and 'browser_compatibility' not set")
+}

If we do that, nothing would (need to) change elsewhere. E.g. the way Yari converts the <div class="bc-data" id="bcd:css.properties.margin"> would be unaffected.

I guess we can do a big search-and-replace one-off (or in batches) where we carefully fix index.html pages more or less one at a time.

Biggest question; should it be bcd_query: instead? Easier to not misspel and more accurate as to what it is.

[escattone]

@peterbe That's exactly my understanding (after talking to @wbamberg) as well.

[wbamberg]

If we do that, nothing would (need to) change elsewhere. E.g. the way Yari converts the <div class="bc-data" id="bcd:css.properties.margin"> would be unaffected.

Yes, exactly!

I guess we can do a big search-and-replace one-off (or in batches) where we carefully fix index.html pages more or less one at a time.

Biggest question; should it be bcd_query: instead? Easier to not misspel and more accurate as to what it is.

I don't feel strongly here, but would vote for browser_compatibility: I agree it's harder to write but it is easier to read, and reading happens more often than writing.

[sideshowbarker]

Biggest question; should it be bcd_query: instead? Easier to not misspel and more accurate as to what it is.

I don't feel strongly here, but would vote for browser_compatibility: I agree it's harder to write but it is easier to read, and reading happens more often than writing.

Truncating it to just browser-compat would give us something reasonably short and easier to not misspell — while also aligning with the mdn/browser-compat-data repo name.

[chrisdavidmills]

Biggest question; should it be bcd_query: instead? Easier to not misspel and more accurate as to what it is.

I don't feel strongly here, but would vote for browser_compatibility: I agree it's harder to write but it is easier to read, and reading happens more often than writing.

Truncating it to just browser-compat would give us something reasonably short and easier to not misspell — while also aligning with the mdn/browser-compat-data repo name.

I think I agree with @sideshowbarker — this would be shorter and easier to type. I don't have a strong opinion though...people will largely copy and paste it, and not write it out from scratch.

[peterbe]

I quite like the hyphenation because it feels more human. browser_compat looks like a programming variable name, whereas browser-compat looks like something a writer would type into a CMS.

My solution takes quite a lax stance. All and anything that's in the front-matter is available on the env object inside the .ejs code. So you can call it whatever you like in a sense, but you just need to align you edits to the front-matter with the relevant .ejs file that uses it.