Enable the renderer to omit section headings

[wbamberg]

(as will become apparent, I'm not sure if this issue should live in stumptown or mdn2)

We now have sections demarcated in the Markdown using H2 headings, and this get reflected in the rendered HTML.

But there's another problem: in the MDN pages we don't always want to show a heading for every section. In particular "Short description" and "Overview" don't get a heading: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video.

In the current system we don't have a way to express this.

I can think of a couple of options:

1. we keep stumptown the same, but mdn2 (the renderer) gets some config data telling it which headings to include. This is of a piece with this suggestion: Expose recipe #27 (comment) that we might want to separate the "recipe" into stuff that describes what documentation we need to supply for an item (which is stumptown's realm), and stuff that describes how we want to present that documentation in MDN (which is mdn2's realm).

2. we change (again!) the way we represent sections, to omit titles for sections that should not get headings.

It feels to me like (1) is the right thing to do, because this is a rendering issue really. And I'm concerned we will keep coming up with issues like this, and eventually we will need to address it properly. But I'm concerned about duplicating information in the recipe and then having to worry about them staying in sync.

@ddbeck , @Elchi3 , @peterbe , I'm interested in opinions about this, both about the overall approach and details of how we could do it.

[ddbeck]

I agree that option 1 is the right thing to do.

Option 2 seems like a real loss and would require stumptown consumers to bring a lot of their own strings for legitimate uses of those untitled sections. Just as an example, I was thinking the other day that it'd be nice to have a command-line stumptown tool, where running stump html.elements.button gets you a tidy, man-like view of the content for button. In that context, I'd probably want the "Overview" heading.

(Also now's probably the wrong time to mention it, but I wonder if the short description doesn't deserve to be a top-level item alongside title, in the JSON output.)

[wbamberg]

OK so if we are going to do this we need to think about things like:

• what's a good way to represent pages to the renderer (mdn2)?
• what are recipes in stumptown for anyway?
• what are we going to call all these things?

Here are some suggestions. Any kind of feedback's very helpful.

What are (a) stumptown_recipes and (b) mdn2_recipes for?

• stumptown_recipes are for validating the content, to make sure it has all the bits it needs. They're also for stumptown consumers, to let them know what must and may be in the content

• mdn2_recipes are for building MDN pages based on the JSON content: they tell mdn2 what needs to be in the page and in what order

They could be different in cases like:

• mdn2 wants an order defined for the things, stumptown doesn't
• mdn2 might not include things that are in stumptown (for example if we decided not to show formal syntax but still wanted it in the JSON for some other consumer)
• mdn2 wants particular ways to customise the content it shows (e.g. omitting headings for short_description)

What's a good way to represent mdn2_recipes?

Here's one suggestion, to give us a starting point:

- renderer: prose
  config:
    - section: short_description
    - heading: false
- renderer: interactive_example
- renderer: prose
  config:
    - section: overview
    - heading: false
- renderer: attributes
- renderer: additional_sections
- renderer: prose
  config:
    - section: usage_notes
    - heading: true
- renderer: examples
- renderer: info_box
- renderer: prose
  config:
    - section: see_also
    - heading: true

It's a list of objects, each of which has a mandatory renderer property and an optional config property.

• renderer is the name of a software component that knows how to render a piece of an MDN page from the JSON. For example, the renderer for attributes is: https://github.com/peterbe/mdn2/blob/master/client/src/ingredients/attributes.js.

• config is some renderer-specific config data. We only have these for the prose renderer, and it contains two things: the name of the prose section, and whether to include a heading.

Then mdn2's top-level renderer goes through this, calling each sub-renderer with the JSON and its config.

@peterbe also suggested not using config files for this and just hardcoding the set of renderers. Personally I'd prefer config files but I'm probably not that one maintaining mdn2 so it isn't my call.

What are we going to call these things?

I don't know really. @peterbe pointed out today that "recipe" might not fit the stumptown thing very well. "manifest" in its original sense seems like a better fit, but it's totally overloaded.

[ddbeck]

re: What are (a) stumptown_recipes and (b) mdn2_recipes for?

stumptown_recipes are for validating the content, to make sure it has all the bits it needs. They're also for stumptown consumers, to let them know what must and may be in the content

I'd like to challenge that second sentence a little. stumptown consumers have slightly different needs: they need guarantees about what they'll find in the JSON (and, presumably at some point, the package API or however else we want to provide stumptown's data). We probably need something like BCD's JSON schema and schema documentation. In an ideal world, as a consumer, you could probably pass the stumptown object in as context for a template (à la handlebars or jinja) and have a pretty good idea of what's definitely going to be in the JSON payload and what's optional. Then the consumers can make good decisions about they want to show or ignore.

Thus, stumptown recipes would be to support authorship and inform the shape of the build, but you shouldn't need them for consumption. Effectively, they're a private API for our content. For mdn2, a recipe would be a template that fills in some HTML with stumptown content (some obligatory, some ignored, some if-available).

re: What's a good way to represent mdn2_recipes?

For mdn2, I'd expect recipes to be, well, templates that stuff stumptown strings into HTML in particular ways.

I'm going to preface this next bit by saying that I only know React by reputation, but I hear it works a bit like Vue (which I do have experience with). This is highly, highly speculative on my part. I'd expect that mdn2 "recipes" and "renderers" to be the React components themselves, as glorified templates. For example, in Vue, I'd have components that:

• Fill the "renderer" role, such as <prose-section heading="{{ stumptownSection.title }}" body="{{ stumptownSection.content }}"> or <compat-table bcd="{{ stumptownObject.browser_compatibility }}">. These would get reused in lots of places.
• Fill the "recipe" role, such as <html-element some-context-prop="{{ someStumptownObject }}">. I'd expect a small number of these, where their overall structure tells us the order of the content.

This seems a little more direct than a config file. It says to me, "hey, if you change this component, you're going to do some things to resulting web page." More so than a YAML file, at least.

re: What are we going to call these things?

I'd keep calling the stumptown recipes recipes. It's fine. For mdn2, we've got some templates? Components? I'm not sure, but I'm guessing there's some React-ish terminology that Peter can fill us in on.

[peterbe]

I'm guessing there's some React-ish terminology that Peter can fill us in on.

No, you've got it right. The React term is "component". Aka. a JavaScript class that is quite flexible and can contain clever things like early exits, business logic, state (not applicable to us) etc. I think @wbamberg 's latest PR (^ see link above this comment ^) demonstrates this nicely.

[peterbe]

There's a lot going on here but from skimming https://github.com/peterbe/mdn2/pull/18/files my impression is all positive. It's easy to read and keeps things simple. In my view, not having clever abstractions on top of config files is actually more flexible. I say that based on the fact how easy it can become to contribute patches if the code is dumbly simple.

Perhaps I'm just lost in all the PRs flying around but I like the idea that the English for the <h3> tags belongs in stumptown rather than the renderer. Granted, I'd love to have more control over rendering the headings. I.e. the <Prose> component should maybe look like this instead:

function Prose({ section }) {
  if (!section) {
    return null;
  }
  return (
    <>
      {section.title && <h3 id={section.id ? section.id : slugifyTitle(section.title)}>{section.title</h3>}
      {/* The 'section.content' string starts with '<p> ....' not '<h3>...' */}
      <div dangerouslySetInnerHTML={{ __html: section.content }} />
    </>
  )
}

Lastly, stumptown does still need a config that stumptown can use to assert that the prose (and attributes, examples, etc.) can be checked to contain everything expected.

Let's see how things shake out. It's early days so we can go and forth a bit about how the renderer and stumptown meet halfway in the "contract" of what's to expect.

[peterbe]

Uh! I just now realized what Will did in https://github.com/peterbe/mdn2/pull/18/files
There are now two kinds of components for prose. Prose and ProseWithHeading.
It could just be 1 but with smarter smarts about conditionally rendering the <h2> tag.

[wbamberg]

I think this is fixed by mdn/yari#18.

I'm very happy to have broken this dependency and the not-recipe for rendering HTML elements looks very nice to me: https://github.com/peterbe/mdn2/blob/master/client/src/App.js#L167-L181. Thanks for the input, very helpful as usual!

I like the idea that the English for the <h3> tags belongs in stumptown rather than the renderer.

I'm not sure if this means h2 instead of h3. Prose section headers are h2 and are explicitly represented in the JSON, outside the prose content itself. But at the moment authors have a lot of freedom for what lives inside a prose section, and that can and does include h3 headings. So as far as prose sections are concerned no English lives in the renderer.

But yes, I'm happy to keep talking about this as we work on it and see how it feels.

[wbamberg]

It could just be 1 but with smarter smarts about conditionally rendering the <h2> tag.

Sure, I liked having 2 different ones because it made the top-level more readable to me. But it's a minor issue either way.