search

mdn / stumptown-content

Other
22 stars 19 forks source link

Support banners/headers #306

Open wbamberg opened 4 years ago

wbamberg commented 4 years ago

See https://github.com/mdn/stumptown-renderer/issues/350.

I had thought that this would be doable with no changes in stumptown-content because the underlying info is in BCD. But it might be better to expose BCD's "status" in a more accessible place in the JSON. My suggestion in that case would be to include it in the body object, as a new item like:

{
    "type": "status",
    "value": [
        "non-standard", "deprecated"
    ]
}

...that is, a type of "status" and a value which is an array including any of "non-standard", "deprecated", and "experimental". I think if none of these apply the whole item could be omitted.

Then this issue would be fixed by making updating build-json to pull that info out of the BCD, and adding this new item to the built JSON.

@Elchi3 , @ddbeck , what do you think?

wbamberg commented 4 years ago

One thing is that BCD has "standard_track", which inverts the meaning from "non-standard". I think it would be nice to represent this in the JSON as "non-standard", though, since that's the case worth noting.

Also, it's a bit upsetting that "non-standard" duplicates information from the specifications property (see https://github.com/mdn/stumptown-content/issues/126#issuecomment-539448613). I don't know if we should try to address that.

Elchi3 commented 4 years ago

Then this issue would be fixed by making updating build-json to pull that info out of the BCD, and adding this new item to the built JSON.

I think this would be great and I think short term this would get us to remove the macros nicely.

I also want to briefly give some more thoughts on banners or status properties. This stuff has been underspecified for a long time and so over in BCD, we've had discussions about how to best go about this. Some comments on how I see this:

I don't want to derail this, though. Maybe the semantics work on status properties can happen in BCD and stumptown-content will pick this up in the body as you propose. In other words, maybe for now don't worry about all this semantic discussions that we need to get through and just pull whatever comes from bcd in the status block (and also take into account the specfications property in stumptown).

wbamberg commented 4 years ago

I've been thinking about this and here's the weird thing.

Currently, pages point to recipes. A recipe lists the things (ingredients) that should be present in a doc, and we expect (for data ingredients anyway) that the doc's front matter contains an item with the same name as the ingredient. So for example, we have a recipe item data.browser_compatibility and we then expect to see a browser_compatibility front matter item in the page. So an ingredient is a signal to the author to include this thing in the docs. We then use this ingredient set to drive the JSON building: both the things we look for and the order in which we build the JSON.

I like all this.

So, if there's expected to be a status item in the JSON, should there also be a data.status ingredient in the recipes? It seems like there should, otherwise we're being inconsistent here. But since we're actually setting the contents of this item from data contained inside other front matter items (specifications and browser_compatibility), then there's no corresponding front matter item, and that also seems inconsistent and confusing for writers.

I can think of three options:

  1. treat status as a proper ingredient, in recipes, in front matter, and in built JSON. This implies writers have to include a status item in front matter that essentially duplicates specifications and browser_compatibility, or that it just empty. Both of these seem weird. But it makes everything else non-weird.

In defence of this option, we could imagine a world where BCD didn't include status, and then this would be an extra datum the writer has to supply, and then we would have a front matter item for it. In fact I don't think BCD should include status, but I think that ship has sailed.

  1. don't expose status anywhere in stumptown-content. Not in recipes, or in front matter, or in built JSON. Instead, the renderer has to find the data in specifications and browser_compatibility. This tends to break the way the renderer wants to build pages, where it can just walk through the JSON.

In defence of this option, it seems likely that the renderer will have to abandon this approach eventually. For example, we would like to include a "BCD summary" thing at the tops of pages. If we do this, are we really going to do it by having build-json insert a new JSON item that essentially duplicates browser_compatibility?

  1. A half-way house: don't represent status in recipes, or in front matter. But have build-json magically insert it into the JSON. This keeps both ends - authors and the renderer - from being weird, but makes build-json weird.

@ddbeck , @Elchi3 , any wisdom?

(Edited to add options, after thinking a bit more.)

ddbeck commented 4 years ago

To further complicate things, what about a fourth option:

In recipes, we use prose.some_section to show that we expect some Markdown (and, in scraping, some H2 in the wiki) and data.some_field to show that we expect some frontmatter. Can we use some third notation to show that an ingredient arises from some other authored thing? Perhaps generated.status or derived.status would communicate that the author isn't meant to create that content themselves, but still lets us include status in the recipe.

(Some day, I think it will be good to generate documentation for authors and for JSON consumers based on the recipe file itself. What the recipe means varies a lot, depending on which side of build-json you're on.)

peterbe commented 4 years ago

I'm a little bit weak on context but I think I can understand the scary implicitness of it working even if the front-matter doesn't have something that it's supposed to have. One option would be to have, in the front-matter, status: generated-from-bcd

Hypothetically, would be it possible to overide what the the "BCD computation" does and manually type it? Like this status: deprecated, almost-overdue, experimental-node

wbamberg commented 4 years ago

To further complicate things, what about a fourth option:

In recipes, we use prose.some_section to show that we expect some Markdown (and, in scraping, some H2 in the wiki) and data.some_field to show that we expect some frontmatter. Can we use some third notation to show that an ingredient arises from some other authored thing? Perhaps generated.status or derived.status would communicate that the author isn't meant to create that content themselves, but still lets us include status in the recipe.

I like this (especially generated). It's expressive of what's going on, doesn't lie, and is simple for both authors and renderers. I felt in the meeting today some sympathy for the idea that status might not be best placed in BCD, and this option also seems to offer us a route towards making status a front matter ingredient, if we ever chose to do that.

I'm a little bit weak on context but I think I can understand the scary implicitness of it working even if the front-matter doesn't have something that it's supposed to have. One option would be to have, in the front-matter, status: generated-from-bcd

Yes, we could do that too. But then all authors would have to type the same thing over and over again.

Hypothetically, would be it possible to overide what the the "BCD computation" does and manually type it? Like this status: deprecated, almost-overdue, experimental-node

I don't think we would want to do this, because that breaks the idea of a single source of truth.