(Auto)EmbedLiveSample is not working correctly

[wbamberg]

See also mdn/content#10758.

It seems that if a page has a structure like this:

## A heading

{{EmbedLiveSample}}

### HTML

(the HTML code block)

### JavaScript

(the JS code block)

...then the code blocks aren't found. But they should be, according to the spec (https://github.com/mdn/content/discussions/5803#discussioncomment-842706), because they are in the same section as the {{EmbedLiveSample}} call. Perhaps the implementation isn't looking in subsections of the current section?

[OnkarRuikar]

This works if we put the headings one level deeper:

### Example

{{EmbedLiveSample}}

#### HTML

(the HTML code block)

#### JavaScript

(the JS code block)

It doesn’t work if a live sample is spread across H2 and H3 sections. It is because yari puts H2 and H3 sections in separate <section>s. They are not in same hierarchy in DOM. Though they appear to be hierarchical due to styling, physically they are not.

The PR #1811 split H2 and H3. So H3 content is no longer placed under H2 header tree. That is why the macro call in H2 can’t find the code in H3 headings.

---

After all these years we can’t revert #1811 easily.

And if try to accommodate this in the auto embed live sample logic, then there will be a lot of hardcoding around H2 and H3 tags. And many possibilities will have to be handled around the H2-H3 boundaries. 😱 The logic will get even more complex. There will be a lot of bugs🐞🐛🪲.

Also, the pages that rely on this bug will break after we fix this. Finding them won’t be easy.

Do we prefer auto embed over explicit embed(i.e. provide id)? Which one is considered a better practice?

[wbamberg]

Well that's fun. Great digging @OnkarRuikar ! I can't comment on the implementation, but as for this:

Do we prefer auto embed over explicit embed(i.e. provide id)? Which one is considered a better practice?

...the history is that this was considered as a way to help address a problem that the Markdown conversion introduced. Before Markdown we could have explicit id attributes on headings (or anything for that matter) that EmbedLiveSample could reference. This meant that the ID could be stable when the heading text changed and in particular when the page was translated.

But in Markdown the ID is always taken from the heading text, so we were concerned that this would be a maintenance problem for authors. So we thought that if we can implicitly select code blocks from the page structure, this would help with that. There's background on this in mdn/content#3548.

In practice, because of bugs like this, we haven't used it much, and we're almost a year on from Markdown conversion at this point. If we do still want to start using it widely, I guess in practice it would be OK to disallow the particular usage that gives rise to this bug (it's certainly niche) as fixing it looks hard.

Also cc @SphinxKnight who has insight from the localization side :).

[caugner]

@wbamberg or @SphinxKnight or @OnkarRuikar Could you please check if this is still an issue? If so, we would accept a PR that fixes this.

[OnkarRuikar]

The issue exists. Following code

---
title: Authoring MathML
slug: Web/MathML/Authoring
tags:
  - Beginner
  - MathML
  - MathML Project
---

## A heading

{{EmbedLiveSample}}

### HTML

```html
<h1>hi!</h1>
```

### CSS

```css
h1 {
  color:red;
}
```

throws error:

Error: MacroLiveSampleError within .../index.md, line 11 column 19 (unable to find any live code samples for "19" within /en-US/docs/Web/MathML/Authoring)

This is a very low severity issue as no page at the moment starts with a live sample in level two ## intro section.

[wbamberg]

no page at the moment starts with a live sample in level two ## intro section.

Except for the two that are referenced in mdn/content#10758 (comment) ?

https://developer.mozilla.org/en-US/docs/web/html/element/input/date#examples
https://developer.mozilla.org/en-US/docs/web/html/element/input/month#examples

Still as I said above:

If we do still want to start using it widely, I guess in practice it would be OK to disallow the particular usage that gives rise to this bug (it's certainly niche) as fixing it looks hard.