-
Notifications
You must be signed in to change notification settings - Fork 19
Support info boxes in HTML element recipes #106
Comments
I agree! |
To be honest, I don't really understand the info boxes (I trust that they exist for a good reason though), so really I defer to you and Florian's judgement on this. But, all other things being equal, I like flattening out the recipes and I endorse the related changes in #107. |
Given a set of content items of a particular type - "HTML elements" or "CSS properties" or "Web API events" - there are typically some set of facts that every item in that type will possess. For example:
It seems helpful to users to present these things consistently, so an experienced user will always know where to find the initial value of any CSS property. That I think is the motivation for these info boxes. At the moment in Kuma these boxes are sometimes built by macros and sourced from mdn/data, and they're sometimes artisanally crafted by writers out of raw HTML. In stumptown of course we would like to build them all from data. But I'm not sure how we should organize the data at this point. It seems that they are fundamentally a collection of name/value pairs which are naturally represented as a table. But different types of thing want different items in the collection, of course, and we would like to be able to validate that a given type contains the right set of items - so, say, every CSS property contains an entry for "initial value". |
Ah, OK. Thank you for the explanation, Will. I suspect this is the sort of thing that may be of interest to other consumers (e.g., I can imagine wanting to query for a CSS initial value, without really needing to consume much other content). I expect, if we get other consumers, then we will revisit this, but I say this is good enough for now. 👍 |
The HTML element recipe looks like this:
So
body
is an array. All except one of its elements are strings, which map onto particular pieces of a page. In we try adopting this proposal, then it will be processed into an array of all the information the renderer needs to render that page piece (e.g. all the BCD, or all the example descriptions and sources). The renderer can then just walk through that array rendering each piece.For these elements that are strings, there is some mandatory internal structure we expect to see in the content - for example, examples are expected to have a particular structure of sources and descriptions and titles. The recipe doesn't define that structure (but content linting should still enforce it).
But
info_box
is different. It's not a string, it's an object which consists of an array of strings, which in turn map onto values in the element's front matter. The output in the JSON still ought to be a thing calledinfo_box
(because it's rendered as a single unit) but in this case the recipe is defining the internal structure of the info box.This is inconsistent, and that becomes very obvious when you try to write generic code to process recipes.
I think we should stop doing this, and instead define the recipe like:
...and define the info_box internal content separately, as we do for other items:
I would as usual be happy to hear what @Elchi3 or @ddbeck think.
Acceptance criteria:
The text was updated successfully, but these errors were encountered: