Removal of redundant Markdown language headers

[OnkarRuikar]

Introduction

The code sections on the MDN website are now showing the language in their captions. This has made the existing language headers written in markdown content redundant:

It is apparent that the repeated language mention is unnecessary. And many of us want to get rid of this boilerplate stuff in the Markdown content.

This discussion is about whether to keep the markdown headers(### HTML). And if we remove them then how it should be done.

History

This header structure was adopted to collect the code from example sections to display embedded live sample outputs. For more information refer the original discussion on this implementation: #3548 [Markdown] Decide how to represent live samples.
In short two, out of three, options were prominent, and option 3 was selected.

Option 3: use headings implicitly

Heading levels (not heading IDs) were considered to group the HTML,CSS, and JS code blocks. This is what we have in use today.

## Examples

### An example
// JS code block for EmbedLiveSample1

{{EmbedLiveSample1}}

### Another example
  #### JavaScript
    // JS code block for EmbedLiveSample2
  #### CSS
    // CSS code block for EmbedLiveSample2
  #### Result
{{EmbedLiveSample2}}

This option was chosen because we wanted to have prose considered as part of the live samples as well and not just the code.

Option 2: use a class identifier on the code blocks

Mentioning this because now this has been implemented and it is ready to be used.

```html live-sample___example_one
<p>Here's a paragraph</p>
```

```css live-sample___example_one
p {
    background-color: pink;
}
```

{{EmbedLiveSample("example_one")}}

Concerns

1. Prose are part of the live sample and there won't be a way to distinguish them. If we remove these headers then there won't be a way to associate prose with corresponding code blocks.
   I think this is a noble thought. But we have never capitalized on this grouping. Current macros extract only the code. These headers are not being used in the extraction, only the closest parent of the macro call is sought.
   Let me know if there is any tool or third party extracting these prose using this association. Do we really have plans to extract entire live sample along with prose? A possibility was mentioned of including prose in the playground. Are we really going to do that?
   Also, not all live samples are atomic. Some of them build on top of previous samples on the page, and some live samples mention previous samples. So such extraction of entire live samples would require rewording in a lot of them.
   If we really don't have any plans for prose then we shouldn't keep this concern holding other stuff happening, e.g. Option 2 mentioned above.

2. Loss of coherence in some cases
   If we simply remove the headers haphazardly then, in some cases it will be hard to tell if a discussion is referring to code block above or below it.

3. Should ### Result header be removed too?
   If we add a customizable caption, with "Result" as default, to the output box then the ### Result header would also become redundant.

4. Please add to the list if you have any...

Stats

Note, only live samples with #+ HTML, #+ CSS, and #+ JavaScript headers are considered, because we are replacing that only.

Live sample with only the headers and without prose - 1221 (989 files)
API - 389 files
CSS - 528 files
HTML - 43 files
Learn - 7 files
JS - 3 files
SVG - 11 files
Others - 8

Live samples with prose - 110 (95 files)
API - 43 files
CSS - 38 files
HTML - 9 files
Others - 5

Solutions

These solutions are not exclusive; we can combine them. Also, it should be ok if we keep some exceptional live samples as it is, because we are not changing the macro implementation so they will still keep working.

a. Replace the headers with magic comments to mark the prose boundaries
To keep the code-prose association intact we could simply replace the headers with HTML magic comments like this:

## Some Example

This does bla bla bla.

<!-- live-sample-section html -->
Discussion about HTML
```html
<!-- code -->
```

<!-- live-sample-section css -->
Discussion about CSS
```css
/* code */
```

<!-- live-sample-section js -->
Discussion about JS
```js
// code
```

This way the headers won't be rendered and we'll have a way to separate sections.

b. Make code section language captions less prominent and don't remove any content headers.

This way the repetition won't be noticeable.

c. Simply remove headers where there are no prose. Sections that match following template.

### HTML
```html
<!-- code -->
```

### CSS
```css
/* code */
```

### JavaScript
```js
// code
```

I see no harm in doing this first if we decide to remove the headers.

d. Update headers with prose manually
Where it is not obvious, update prose mentioning which section they are referring:

### example

#### CSS
```css
/* code */
```
In above code...
As we can see in the following code...
```JS
// code
```

We can do this after solution c. has been applied.

e. do not touch meaningful headers

### Example

#### CSS for the PIP video player
```css
/* code */
```

### PIP Video player JS code
```js

Let's not modify such cases. These will keep working as it is as we are not updating the macro behavior.

f. for result section add customizable title to the output box and remove those ### Result headers as well
The macro call may look like this {{EmbedLiveSample("Example_one", 100%, 600px, "My Result")}}:

g. Do absolutely nothing keep the structure and code section captions as it is.
This is the easiest solution.

Plan

To be decided when we pick some of the solutions mentioned above. It'll be like raising an issue to track implementation of solutions c&f then d&f for each content areas.

[wbamberg]

I think this is a noble thought. But we have never capitalized on this grouping.
..
Let me know if there is any tool or third party extracting these prose using this association. Do we really have plans to extract entire live sample along with prose?

I'm working on this at the moment. Honestly I wouldn't bring this up if it wasn't a real concern.

There are a few principles I'd like to suggest:

• we don't break the coherence of examples by ignoring prose
• we have a consistent approach to all live samples: so we don't have headings for ones with prose, and no headings for ones without prose.
• we try to keep things simple for authors and reviewers. Contributing to MDN is hard enough as it is.

Another option is:

• no headers, and only allow prose in certain places (for example, at the start of the example:

### My example

An explanation of my example.

```html
...
```

```css
...
```

{{EmbedLiveSample("My example")}}

OR have a convention that prose only refers downwards:

### My example

An explanation of my example.

```html
...
```

Another explanation! But this is implicitly attached to the CSS block.

```css
...
```

{{EmbedLiveSample("My example")}}

I think one problem with implicit things like this is that they're much less obvious for authors and reviewers. For that I suppose, although the HTML comments are horrible to write, they are at least very explicit.

[OnkarRuikar]

so we don't have headings for ones with prose, and no headings for ones without prose.

:confused : Are you agreeing on having no headings at all?

no headers, and only allow prose in certain places (for example, at the start of the example:

-1 For long examples pros near code are better.

OR have a convention that prose only refers downwards:

+1 This one is much better. Or we can also have pros only referring upwards. Intention being readers will see code first then read the explanation for it. Except for the intro section that could be extracted as the text between the macro's parent tag and first code block.

I'm working on this at the moment. Honestly I wouldn't bring this up if it wasn't a real concern.

Is it related to the new project? I had no idea. That is why I kept wondering why we needed it.

---

You haven't mentioned anything about ### Result header. It has been used inconstantly. Should we keep it? Remove it and have it on the output box's title bar?

[bsmth]

Just adding a +1 that if we are removing the headers, we use this approach:

OR have a convention that prose only refers downwards

and with this part:

You haven't mentioned anything about ### Result header. It has been used inconstantly. Should we keep it? Remove it and have it on the output box's title bar?

If we remove all the other headers, we should also remove ### Result - this is also implicit (programmatically speaking or from the tooling perspective, we know it's where the macro is). So having "Result" in the rendered title or "My example" (example section heading) or "CSS + HTML" or any combination of these makes sense.

[wbamberg]

OR have a convention that prose only refers downwards:

+1 This one is much better. Or we can also have pros only referring upwards. Intention being readers will see code first then read the explanation for it. Except for the intro section that could be extracted as the text between the macro's parent tag and first code block.

This is nice in lots of ways, but its big drawback is that it's a very implicit and subtle rule, so it's easy for authors to do the wrong thing and hard for reviewers to spot violations (and impossible for scripts to discover it). Compared with, say, HTML comments, which are ugly and horrible to write, but much more explicit and easy to check.

so we don't have headings for ones with prose, and no headings for ones without prose.

:confused : Are you agreeing on having no headings at all?

I mean, we should be consistent. Just talking about live samples in reference pages: we should not have headings for some live samples and not for others. Either they should all have headings, or none of them should.

[wbamberg]

I'm working on this at the moment. Honestly I wouldn't bring this up if it wasn't a real concern.

Is it related to openwebdocs/project#174? I had no idea. That is why I kept wondering why we needed it.

Yes. But although this project is new, it's a thing we have wanted to do for a long time.

[wbamberg]

It's also possibly worth distinguishing live samples in the reference documentation (i.e. anything with a page-type not equal to guide|landing-page|how-to|tutorial|tutorial-chapter) from code samples elsewhere.

Live samples in the reference docs should follow a much more consistent structure than others, and extractability is much more of an issue for them. So we might want to do this only for reference documentation, and leave guide pages alone.

[OnkarRuikar]

and leave guide pages alone.

Not regarding the strict structure, guide and tutorial pages hardly ever use bland language headers(### HTML). The ones that use need to be updated.

[hamishwillee]

FYI I created a duplicate of this here: https://github.com/orgs/mdn/discussions/439 . I'm in favour.

[estelle]

If you want to test what it would look like without the headers, add the following to the css

/* all H4 elements with an id of HTML */
h4[id="HTML"], 
/* any h3-h6 heading where the id contains html or css, case insensitive, if that heading has a code-example as the next sibling *?
:is(h3, h4, h5, h6):where([id*="html" i],[id*="css" i]):has( + .code-example) {
  /* don't display the heading  */
  display: none;
}

[estelle]

We would need to use the following selector instead:

:is(h3, h4, h5, h6):where([id*="html" i],[id*="css" i]):has( + .code-example + :is(h3, h4, h5, h6))

this limits the hiding to only headers that have a single block of code, no explanation. This is necessary, as there are some areas where we divvy up the code into several blocks and explain it.

And, since we do that, we should NOT be removing these headers.

[OnkarRuikar]

This will work but we still have to ask contributors to keep using the headers in the content, which will be hard to enforce.

[hamishwillee]

Well, that assumes that the headers are useful: my assertion is that they are not.

[OnkarRuikar]

Following two options were prominent in the Editorial meeting yesterday. In order to make the decision we decided to have a poll. Choose one of the two options in the reply to this message. Any suggestions are welcomed too.

Option A

Move the code block caption to right so it won't be seen as repeated due to the headers:

This cosmetic only change saves us from modifying anything in the content. This doesn't remove the language headers in content. We can iron out exact looks later.
This received 4 out of 7 thumbs-ups in the meeting. I couldn't collect the names at that time so those people have to vote again.

Option B

Remove the language headers and restrict prose location either only at the top of all the code blocks or before each code block. No decision was made regarding this option. So if we choose this option we'll still have to decide how to arrange prose among code blocks.
With this option we'll have change the example guidelines and update existing examples with prose.

[OnkarRuikar]

I like option A because it requires a small change and it will be on platform (mdn/yari) side.

[estelle]

I prefer option A.
Semantically, the headers are leveled headings; the code block heading is a span.
Sometimes there are multiple code blocks with explanatory text in between under a single heading.

That said, sometimes the heading are not necessary; notably in the HTML elements example sections, where fortunately they don't have the headers when not necessary. They should continue to not be required.

[Josh-Cena]

I suggest both option A and removing language headers whenever there's no extra prose.

[hamishwillee]

I like "Option C" - remove the headers.

Where's the evidence that extracting all or part of the example is actually useful? If it is useful where is the evidence that if MDN modifies an example it won't break those users?

Unless we can actually show more than theoretical value a discussion of how we can go about keeping them seems a bit silly.

[yarusome]

A tangential question: Could the headers of live examples show the full name of the code's language? E.g. "JavaScript" instead of "JS", "Markdown" instead of "MD".

Update: Filed mdn/yari#9628.

[hamishwillee]

IMO that would do no harm and might do some good. You'd have raise an issue in https://github.com/mdn/yari

[dipikabh]

My vote is for:

• Removing markdown headers in content (IMO we should not not have a mix of keeping the headers in some places and removing in other places based on a condition)
• For styling, keeping the language in code block aligned on the left. The right side is a bit busy with options for Play and Copy.
• I don't think we should have a strict rule about prose placement but rather a guideline so that that's what is followed in most cases but leaves room for other types of situations. I've been following this style (a mix of using "downward" and "upward" explaining text) and is my preference.

    ## Examples

    ### <example-specific section title, preferably worded as an action, such as "Creating...", "Demonstrating...">

    "This example demonstrates..."
    (Prose here should state the key objective of the example and possibly describe the situational set up.
    Optional but recommended)

    "In the code below, ..."
    (any notable mentions about the HTML code, optional)
    ```
    html live-sample___example_one
    <p>Here's a paragraph</p>
    ```

    "In the code below, ..."
    (any notable mentions about the CSS code, optional)
      ```css live-sample___example_one
    p {
        background-color: pink;
    }
     ```

    {{EmbedLiveSample("example_one")}}
    "You'll notice that...", "The span here is green because..."
    (Statements to explain the resultant frame.
    This is an upward explainer. Optional but recommended) 

• If we do need to keep the link between prose and code, I like this suggestion:

"a. Replace the headers with magic comments to mark the prose boundaries".

This can be applied to both ends of the code block to allow for prose placement before or after code. Too much text in the magic comments at the moment, which can be worked out further, but this is the general idea:

   <!-- example_one_prose -->
   The example intro
 
   <!-- example_one_html start -->
    HTML code explainer
    ```html live-sample___example_one
    ```
    If required, further explanation or highlights about the code
   <!-- example_one_html end -->

   <!-- example_one_css start -->
    Notable points about the code
    ```css live-sample___example_one
    ```
   <!-- example_one_css end -->

   <!-- example_one_result start -->
    {{EmbedLiveSample("example_one")}}
    Further explanation or highlights about the code
   <!-- example_one_result end -->