[Markdown] Decide how to represent code blocks

[wbamberg]

This issue is to decide how we will represent, in Markdown, blocks containing example code. I think it should be pretty obvious in general but it's worth going through the details, and you never know.

Currently we use <pre> blocks of course, with classes for syntax highlighting:

<pre class="brush: js">
...
</pre>

In Markdown we can use fenced code blocks for this. The nice thing about these is that you can have an "info string" after the opening fence. From the GFM spec:

The first word of the info string is typically used to specify the language of the code sample, and rendered in the class attribute of the code tag

So we can use the first word to identify the language:

```js
const x = 1;
```

=>

<pre class="brush: js">const x = 1;
</pre>

We use other classes in code blocks, and the obvious suggestion is to support them, too, by putting them in the info string:

```js fee fi fo fum
const x = 1;
```

=>

<pre class="brush: js fee fi fo fum">const x = 1;
</pre>

But we might want to take the opportunity to clean things out a bit here. A quick survey of the JS docs yields the following classes on code blocks, in addition to language classes:

• example-good
• example-bad
• highlight[x,y,z]
• line-numbers
• no-line-numbers
• hidden

example-good and example-bad

Style this as a good/bad example (e.g. https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors/Illegal_character#mismatched_characters).

This is used extensively in the JS docs (~350 usages) especially the error reference. We should probably keep it.

highlight[x,y,z]

Highlight the lines with the given line numbers.

This isn't currently working, nor is is documented at https://developer.mozilla.org/en-US/docs/MDN/Guidelines/CSS_style_guide. Sometimes (about half the time apparently) people do highlight:[x,y,z], and because it's broken and undocumented, I don't know which is correct.

So for those reasons, although it does seem to be used several hundred times in our docs, I'd vote to discard it.

line-numbers and no-line-numbers

I count ~49 instances of line-numbers and ~500 instances of no-line-numbers across our docs. It doesn't seem to work, we seem to get no line numbers either way. I would like to discard this, and personally I like not having line numbers.

But if we want to have line numbers for some examples, we need a way to switch if off especially for syntax box-type code blocks (e.g. https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice#syntax).

hidden

Don't render the block.

I think we need hidden for code blocks in live samples, where people want the code to contribute to the live sample but don't want to show it (for example, for a bit of CSS to make the example look nicer - although we might argue that it would be better and more consistent for our examples to use common styles by default...).

But actually all the (several hundred) examples of this I can find that relate to live samples use it on a <div>, not a code block. For example, like this:

content/files/en-us/web/css/text-justify/index.html

Lines 54 to 60 in 1d2c354

	<div class="hidden">
	<pre class="brush: html">&lt;p class="none"&gt;&lt;code&gt;text-justify: none&lt;/code&gt; —&lt;br&gt;Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc ornare maximus vehicula. Duis nisi velit, dictum id mauris vitae, lobortis pretium quam. Quisque sed nisi pulvinar, consequat justo id, feugiat leo. Cras eu elementum dui.&lt;/p&gt;
	&lt;p class="auto"&gt;&lt;code&gt;text-justify: auto&lt;/code&gt; —&lt;br&gt;Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc ornare maximus vehicula. Duis nisi velit, dictum id mauris vitae, lobortis pretium quam. Quisque sed nisi pulvinar, consequat justo id, feugiat leo. Cras eu elementum dui.&lt;/p&gt;
	&lt;p class="dist"&gt;&lt;code&gt;text-justify: distribute&lt;/code&gt; —&lt;br&gt;Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc ornare maximus vehicula. Duis nisi velit, dictum id mauris vitae, lobortis pretium quam. Quisque sed nisi pulvinar, consequat justo id, feugiat leo. Cras eu elementum dui.&lt;/p&gt;
	&lt;p class="word"&gt;&lt;code&gt;text-justify: inter-word&lt;/code&gt; —&lt;br&gt;Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc ornare maximus vehicula. Duis nisi velit, dictum id mauris vitae, lobortis pretium quam. Quisque sed nisi pulvinar, consequat justo id, feugiat leo. Cras eu elementum dui.&lt;/p&gt;
	&lt;p class="char"&gt;&lt;code&gt;text-justify: inter-character&lt;/code&gt; —&lt;br&gt;Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc ornare maximus vehicula. Duis nisi velit, dictum id mauris vitae, lobortis pretium quam. Quisque sed nisi pulvinar, consequat justo id, feugiat leo. Cras eu elementum dui.&lt;/p&gt;</pre>
	</div>

.

I'll talk about the general usage of hidden on <div> in another issue, but for live samples, I wonder if we'll need to do some conversion like: if you see <div class="hidden">, then apply hidden to all code blocks in that <div>.

[hamishwillee]

@wbamberg

Disagree regarding highlighting as I posted here: mdn/yari#2757

The highlighting was broken in the recent move to github backend. The highlighting exists for a reason and we should put it back, or we need to go through and find some other way to update all those docs that are now broken.

Personally I would like the ability to specify lines and line ranges to highlight, but I'd also be happy with a way to add styling within the code block - e.g. to make some sections bold even if that is not the styling added by the renderer. It is a very useful feature.

I have never seen a real use for line numbers except in conjunction with highlighting when you have multiple lines and want to talk about them separately. Could live with out them. Agree on the rest.

[chrisdavidmills]

Looks mostly good @wbamberg . Some comments on the points you highlight:

• code fences and info string classes for code blocks — yup, I don't think you'll get any disagreement here. This works great for GitHub, and will work great for MDN, and I don't really see there being any other viable option to discuss.
• example-good and example-bad — yup, we need these. I use these in the learning area and in other places too.
• highlight[x,y,z] — i used to use these way back when I first started at Mozilla, but I founf them to be a pain in the ass. If your code block changes and you add a line, you then need to update your line number highlights, and it is annoying. I also think that if a code block is so big that you need to highlight specific lines, you probably ought to break it up smaller. I also think that it is easy to just use other ways of describing the code, e.g. "The querySelector() call at the start of the block does x..." rather than "Line 1 does x" — the former is more descriptive and better for learning, imo. Summary — I am not bothered about these, and would err ron the side of dumping them. Keep it as simple as possible.
• line-numbers and no-line-numbers — I've never used these in my 8 years on MDN. Remove.
• hidden — yeah, I think we might need some other mechanism to recreate this. <div class="hidden"> is quite often used to contain a hidden code block plus a hidden sub heading, so you can then refer to that heading in a live sample macro and have it pull in only that code below the subheading, and not alll of the code in the main section. We could probably rewrite these instances to use require hidden on clode blocks, but it'd be a lot of work rewriting it all.

[wbamberg]

Looks mostly good @wbamberg . Some comments on the points you highlight:

• highlight[x,y,z] — i used to use these way back when I first started at Mozilla, but I founf them to be a pain in the ass. If your code block changes and you add a line, you then need to update your line number highlights, and it is annoying. I also think that if a code block is so big that you need to highlight specific lines, you probably ought to break it up smaller. I also think that it is easy to just use other ways of describing the code, e.g. "The querySelector() call at the start of the block does x..." rather than "Line 1 does x" — the former is more descriptive and better for learning, imo. Summary — I am not bothered about these, and would err ron the side of dumping them. Keep it as simple as possible.

Yeah, I agree with all these points.

line-numbers and no-line-numbers — I've never used these in my 8 years on MDN. Remove.

I think it's not so much, should we have these classes, as:

(1) should we have line numbers in examples (in general, by default), and

(2) if so, should we suppress them in cases like syntax blocks (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice#syntax)?

If the answers are Yes and Yes, then we need some mechanism to control this. (FWIW I think we should not have line numbers in examples, which would mean we don't need this mechanism).

• hidden — yeah, I think we might need some other mechanism to recreate this. <div class="hidden"> is quite often used to contain a hidden code block plus a hidden sub heading, so you can then refer to that heading in a live sample macro and have it pull in only that code below the subheading, and not alll of the code in the main section.

Could you point me at an example of this? I'm having trouble picturing it.

[chrisdavidmills]

I think it's not so much, should we have these classes, as:

(1) should we have line numbers in examples (in general, by default), and

(2) if so, should we suppress them in cases like syntax blocks (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice#syntax)?

If the answers are Yes and Yes, then we need some mechanism to control this. (FWIW I think we should not have line numbers in examples, which would mean we don't need this mechanism).

I agree with you on this. We don't currently make any use of line numbers, and I don't see why we should start.

Could you point me at an example of this? I'm having trouble picturing it.

Here's one:

• The live guess the number game that appears near the top of https://developer.mozilla.org/en-US/docs/Learn/JavaScript/First_steps/A_first_splash
• Here's the hidden bit in the source code: https://github.com/mdn/content/blob/main/files/en-us/learn/javascript/first_steps/a_first_splash/index.html#L55

[wbamberg]

Could you point me at an example of this? I'm having trouble picturing it.

Here's one:

• The live guess the number game that appears near the top of https://developer.mozilla.org/en-US/docs/Learn/JavaScript/First_steps/A_first_splash

• Here's the hidden bit in the source code: https://github.com/mdn/content/blob/main/files/en-us/learn/javascript/first_steps/a_first_splash/index.html#L55

Thanks! So in this case it looks like we want to hide all the source, and only show the output. That seems like a more natural fit for EmbedGHLiveSample - since we have this example as a GitHub page already, is there a reason we couldn't do:

{{EmbedGHLiveSample("learning-area/javascript/introduction-to-js-1/first-splash/number-guessing-game.html", '100%', 320)}}

That seems to work, and has the advantage that we're not duplicating the code in the page and in GitHub.

?

I'm seeing a similar pattern in https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Grids.

[hamishwillee]

I agree with you @chrisdavidmills that highlighting is a pain for the author, but IMO it can be better for the reader, even in quite small blocks of code.

On the other hand, the closer our markdown matches github flavour markdown the better.

Either way though, we still need to fix the cases where it was used and the documentation says something like "see the highlighting". I know it exists, because I injected some when i wrote the Django stuff.

[chrisdavidmills]

Thanks! So in this case it looks like we want to hide all the source, and only show the output. That seems like a more natural fit for EmbedGHLiveSample - since we have this example as a GitHub page already, is there a reason we couldn't do:

{{EmbedGHLiveSample("learning-area/javascript/introduction-to-js-1/first-splash/number-guessing-game.html", '100%', 320)}}

That seems to work, and has the advantage that we're not duplicating the code in the page and in GitHub.

?

I'm seeing a similar pattern in https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Grids.

I have to say I agree with you @wbamberg . So we have a plan for this case too!

[chrisdavidmills]

I agree with you @chrisdavidmills that highlighting is a pain for the author, but IMO it can be better for the reader, even in quite small blocks of code.

On the other hand, the closer our markdown matches github flavour markdown the better.

Either way though, we still need to fix the cases where it was used and the documentation says something like "see the highlighting". I know it exists, because I injected some when i wrote the Django stuff.

Yea, when the time comes to migrate it over, we'll just need to go through the list of highlighting instances, and update them.

[wbamberg]

I'm closing this, since there's a resolution in https://developer.mozilla.org/en-US/docs/MDN/Contribute/Markdown_in_MDN#example_code_blocks.