Should live examples still have sub headings for code type?

[hamishwillee]

Code samples in MDN recently got an explicit "content type" heading like this:

There was some discussion that we no longer need the markdown headings for HTML, CSS, JavaScript, in live examples any more since these are now shown. I like that idea, in that I think it makes the documentation easier to read and it reduces what feels like an artificial constraint on structure.

An argument for keeping the headings is that the enforced structure make it potentially possible to reuse the content elsewhere. I'm unconvinced of the use case.

So the question is - headings or no heading in live examples? If not, then we should update the guideline.

[chrisdavidmills]

I've always been a bit 'meh' about the HTML/CSS/JavaScript headings in live examples — IMO makes the document structure unnecessarily more complex, breaks up the tutorial flow and is better served by just good textual explanation, looks ugly, can almost be a bit patronizing (of course I know this is HTML, why do you feel the need to point it out?!?). The explicit content type headings just double up the pain, and are a good excuse to talk about removing them from the guidelines.

My vote is for no live example headings.

[bsmth]

I like the idea of removing the headings where possible. The "content type" headings are closer to the actual source, we're making visible what is already set on the code block:

### JavaScript

```js
// I know this is JS
```

And to add something else for thought, we also know what the result is, so in cases where we have this header:

#### Result

{{my_macro}} <!-- this is the result -->

For content reuse, I think this should be sufficient, so in general I am +1 on removing them.

Note that there's a discussion here: https://github.com/orgs/mdn/discussions/426

[hamishwillee]

I think the idea that we can usefully extract text in a general way is a pipe dream. We couldn't even reuse text from within MDN using the page macro, and an external dependency is even more risky.

That said, if this were possible, removing the headings would make it harder because then you don't know what prose belongs to what thing. It essentially means that an example is a monolithic block under a heading from a reuse point of view.
But as I say. Nuts.

[Rumyra]

As this is also being discussed here https://github.com/orgs/mdn/discussions/426 I'm closing this to take the conversation there - let me know if you think it should be re-opened