Support info boxes in HTML element recipes

[wbamberg]

The HTML element recipe looks like this:

related_content: /content/related_content/html.yaml
body:
- prose.short_description
- meta.interactive_example?
- prose.overview
- prose.attributes_text?
- meta.attributes
- prose.styling?
- prose.accessibility_concerns?
- prose.*
- meta.examples
- meta.info_box:
    - meta.api
    - meta.permitted_aria_roles
    - meta.tag_omission
- meta.browser_compatibility
- prose.see_also

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 called info_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:

related_content: /content/related_content/html.yaml
body:
- prose.short_description
- meta.interactive_example?
- prose.overview
- prose.attributes_text?
- meta.attributes
- prose.styling?
- prose.accessibility_concerns?
- prose.*
- meta.examples
- meta.info_box
- meta.browser_compatibility
- prose.see_also

...and define the info_box internal content separately, as we do for other items:

title: '<article>: The Article Contents element'
mdn_url: https://developer.mozilla.org/docs/Web/HTML/Element/article
tags:
    group: Flow content
info_box:
    - api: HTMLElement
    - permitted_aria_roles:
        - application
        - document
    - tag_omission: none
interactive_example: https://interactive-examples.mdn.mozilla.net/pages/tabbed/article.html
browser_compatibility: html.elements.article
examples:
    - examples/simple-article-example
attributes:
    global: /content/html/global_attributes
recipe: html-element

I would as usual be happy to hear what @Elchi3 or @ddbeck think.

---

Acceptance criteria:

• info box structures are defined and code written to process them into JSON
• info box data is updated for all HTML element and input element pages

[Elchi3]

I agree!
Long time ago, when we were starting to create mdn/data, we also identified these things as "HTML data" (prior art). I think what you describe here will treat these things more like data and that makes sense.

[ddbeck]

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.

[wbamberg]

To be honest, I don't really understand the info boxes

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:

• the DOM API corresponding to this HTML element
• the initial value of this CSS property
• the type of object that will be passed into the event listener

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".

[ddbeck]

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. 👍

[wbamberg]

See also https://docs.google.com/document/d/1fwbTs6uoeAfGjjZef3cOOzG1Bx-S8sbLbCBjzx9gBPY/edit#.