[Markdown] Decide how to represent notes and warnings

[wbamberg]

In MDN people are able to specify that content should appear in little callout boxes: blue for notes, and yellow for warnings.

We specify them using some markup like:

<div class="notecard note">
<p>My note</p>
</div>

<div class="notecard warning">
<p>My warning</p>
</div>

I count about 250 variations of this in the JavaScript documentation, so they're quite widely used.

Since GFM doesn't have native support for this, we need to decide how to handle it.

The output of this issue is an update to the specification for using Markdown in MDN, that details how we'll represent notes and warnings.

[wbamberg]

Options for handling this:

Option 1: use HTML

In option 1 we fall back to HTML. In GFM we can embed Markdown in HTML blocks, so people can write something like:

<div class="notecard warning">

**My warning**: don't ever do this.

</div>

...and it will generate markup like:

<div class="notecard warning">

<p><strong>My warning</strong>: don't ever do this.</p>

</div>

Advantages: it's quite clear what's going on, there's very little magic. Falling back to HTML is a very common approach to dealing with Markdown limitations, and people don't have to learn any new syntax.

Disadvantages: it won't render as a note outside Yari (for example, in a text editor).

Option 2

(from https://github.com/fiji-flo/scratch/blob/main/mdn/markdown-thought-dump.md#noteswarnings-and-the-likes): use blockquotes combined with an h6.

> ###### Note
> This could be a note

Yari can rewrite the markup so it makes sense semantically, but it would render reasonably well in any context that renders GFM.

Advantages: it will render well in any reasonable Markdown context.

Option 3

If a paragraph starts with **Note:** or **Warning:**, it is rendered as a note or warning block.

Advantages: very simple markup, would render OK without special Yari magic.
Disadvantages: only works when a note is a single paragraph.

[chrisdavidmills]

The newest guideline for writing notes and warnings is to include a heading of the appropriate level so they fit into the doc tree, e.g.

<div class="notecard note">
<h4>Note</h4>
<p>My note</p>
</div>

<div class="notecard warning">
<h4>Warning</h4>
<p>My warning</p>
</div>

Of the options you've stated so far, I think option 2 is the best one. It will work anywhere, and is not open to misinterpretation.

I also wonder if there is a kind of hybrid option of 2 and 3 worth looking at? Since going forward notes and warnings are supposed to include a heading, you could state that any document section whose heading contains the text "Note" or "Warning" is rendered as a note or warning, whatever the level of the heading. Single and multiple line would work equally as well, e.g.

## Note

This is my note.

or

## Note

This is my note.

This is my note's second line.

[sideshowbarker]

I agree that option 2 seems best. It just works, off the shelf — with no overhead.

I definitely wouldn’t want us to do option 1. If we’re moving away from HTML, then let’s move away from HTML. All the way. Or at least, let’s only use HTML for cases where we absolutely have no other reasonable option.

But for the Note case, we have a reasonable option: Option 2 — just using ">" with a Note heading.

I also wonder if there is a kind of hybrid option of 2 and 3 worth looking at? … you could state that any document section whose heading contains the text "Note" or "Warning" is rendered as a note or warning, whatever the level of the heading.

## Note

This is my note.

This is my note's second line.

I think the problem that’ll run into is that Notes aren’t always sections — that is, Notes aren’t always followed by other headings, but are instead sometimes followed by normal paragraph text. Consider this:

## Note

This is my note.

This is my note's second line.

This is a normal paragraph which follows the Note; it’s not part of the Note.

In other words, in order to handle the case where a Note contain multiple paragraphs but is followed by some paragraph that’s not intended to be part of the Note, then what’s needed is some way to indicate, line-by-line what’s part of the Note and what isn’t — to indicate where the Note starts and where it ends. So that’s why we need ">".

[chrisdavidmills]

I think the problem that’ll run into is that Notes aren’t always sections — that is, Notes aren’t always followed by other headings, but are instead sometimes followed by normal paragraph text.

Ah, of course, well explained.

In which case option 2 is definitely best. We could even do multiple lines like this

> ###### Note
> First note paragraph
>
> Second note paragraph

and code blocks and other features would also work in > lines, right? If we ever have code blocks inside notes (which we sometimes do)

[hamishwillee]

Gitbook richquotes plugin does it the "best" I have seen. Very similar to proposal.

Essentially it uses either quote on each line. You can also have code and any other markup you like inside the note.

> **Note** This is first line
> This is second line
>
> This is third line on a new paragraph

or if you don't want multiple paragraphs you can just indent.

> **Note** This is first line
  This is second line
  This is third line

That particular plugin uses the > **Note** to identify the type of note to create - ie it also renders > **Tip** and > **Warning**. I much prefer this over using the heading syntax ###. While the github rendering is probably slightly better for the heading (both shown below) IMO you should never give people the choice as to how big this heading is. The markup should always be exactly the same.

Note This is first line
This is second line
This is third line

Note

This is first line
This is second line
This is third line

Something to consider is whether we will have heading text rendered, and if so, whether we allow custom heading text.

Just for completeness, the other good way I have seen this done is to hijack the code block syntax:

``` note
This is first line
This is second line
This is third line
```

This renders as plain code as shown below. To my mind not quite as good as the other way. In particular, because it becomes impossible to specify a code block inside a note.

This is first line
This is second line
This is third line

[wbamberg]

I agree that if we go this way, **Note** is better than ###### Note, because it doesn't abuse the semantics so much.

I guess one problem with #2 is localization. If Yari uses "Note" and "Warning" to decide which sort of callout it is (or even, that it's a callout at all rather than a blockquote), do other locales have to use the English word? (that doesn't sound at all good) Or does Yari keep track of all the localizations? Then I guess translators have to know the magic word to use to get the styling.

[hamishwillee]

@wbamberg You're right about localisation being a potential problem. For example I use Crowdin in one project for translation and I'm constantly having to tell translators NOT to translate the "Note" text; this would be even worse if we use automated translation.

My preference is usually to treat the text as untranslatable and render the text as an icon so it doesn't get translated. But the solution here will depend on what we want the output to look like.

[sideshowbarker]

and code blocks and other features would also work in > lines, right?

Yes — with the caveat that in practice you have to be careful about indenting; but with the right indenting, it does work. (Speaking from experience with using it in other projects.)

[sideshowbarker]

If Yari uses "Note" and "Warning" to decide which sort of callout it is (or even, that it's a callout at all rather than a blockquote)… does Yari keep track of all the localizations? Then I guess translators have to know the magic word to use to get the styling.

Right. The set of localized “Note” words we’d need Yari to know is a discrete set, of some relatively manageable length. And to help catch misspellings, it’s imaginable we could have Yari use some Levenshtein-distance thing to catch those. But even worst-case for misspellings, they’d eventually just get caught by eyeballing — in that somebody would notice that the Note didn’t render with the expected special Note formatting.

[ddbeck]

I want to go to bat for option 1.

Option 1 allows editors to be cheaply upgraded to support MDN-specific styling, while still looking acceptable and offering few surprises in vanilla CommonMark/GFM contexts. For example, I found it rather easy to extend the VS Code Markdown preview* to apply a custom style for a notecard warning. Additionally, I think the cumbersome source format is actual an advantage in disguise: notes are often abused, so perhaps they should be difficult to write.

Though Options 2 and 3 have the benefit of looking marginally better in any plain CommonMark context, they force the least-common denominator. Upgrading my editor's preview to support the special case of H6 or **Note** is a rather more substantial project because I'd need to modify the actual Markdown processing.

(Option 2's variation with blockquotes goes a step further. To me, it doubles the surprise of Option 2 to make the least-common denominator preview look better while also making the preview hard to upgrade. I found it to be the least attractive option.)

I have a variation to propose on option 1, but I'm not sure whether alternatives are being considered. I've asked Will about this meta procedural issue out-of-band.

* Another interesting thing here is that, for VS Code, you can do this on a per-project basis, or as a distributable extension (e.g., like the extension that restyles the preview to look more like GitHub). We could check styling or recommended extension configuration into the repository's .vscode directory. I expect similar configuration shortcuts could be provided for other popular editors and tools.

[ddbeck]

OK, I checked in with Will and he said it was OK if I proposed another option:

As a variation to option 1 (let's call it 1a), we could lean into HTML with custom elements, such as <mdn-note> (with a corresponding <mdn-warning>, or something cleverer with attributes). This would have roughly the same disadvantages of a <div>, but it would make a stronger signal to authors (and PR reviewers) when they've gone and done something unsanctioned or discouraged in our Markdown content.

This would also set a nice precedent for "extending" Markdown when Markdown doesn't provide a convenient syntax to overload (like code blocks), as a sort of post-KumaScript. Custom elements are legit HTML, have well-understood parsing, and avoid a host of problems associated with trying to invent your own syntax.

[wbamberg]

FWIW I agree with Daniel about this, and I like 1a. For each of these things GFM doesn't know about, there are four options:

1. use HTML
2. invent our own thing, or use some other quasi-conventional thing (e.g. steal something from Kramdown)
3. stop doing the thing, if we want to stop doing it and the cost of changing the source isn't too great
4. use a macro, if we can and the cost of converting isn't too great

I think we should not underestimate the cost of (2). A big part of the reason for wanting to use GFM is that it has a proper spec that we can lean on, rather than having to define our own syntax. Defining our own syntax means we have to document it ourselves and everyone has to learn it, and any subtleties that aren't immediately apparent.

To me the main reason for avoiding HTML is that it's hard to write. In this case it's not hard, because we can use Markdown inside the <div> (or custom element). There are other cases where it is hard to use the HTML fallback, and in those cases there's a stronger argument for extending Markdown or stealing something from Kramdown (I think this might be the case with <dl>).

I also agree that notes are over-used on MDN, and making people use HTML is perhaps a signal that they should think twice about it.

But: what's most important in this exercise is that we are clear about the tradeoffs of making different choices.

[hamishwillee]

100% agree "most important in this exercise is that we are clear about the tradeoffs of making different choices" - and with most of the rest of ^^^

Probably repeating myself but since I feel pretty strongly about this:

• I wouldn't say that notes are particularly or "measurably" over-used. But perhaps that's because I'm part of the problem.
• The joy of markdown is that editors don't have to care about VSCode or another editing tool.
• One thing I like about markdown is the lack of flexibility and variation. All notes look the same. Less thinking about appearance and more about content.
• A solution that renders well on github would be desirable.
• As an editor I very much prefer not having to use HTML ever. Learning a new syntax for these that has closing tags would be a minor pain.
• Do spare some time to think about the end user writing their first few articles. The less we have to explain and the easier it is, the better.

[chrisdavidmills]

I am unconvinced that the advantages described here outweight the pain of having to write some kind of HTML in the markdown.

I don't necessarily think that the HTML version is loads harder to remember than the markdown suggestion in isolation, but I do think every instance where we ask the reader to break from markdown to using HTML is a bit of cognitive overloard that we don't want to underestimate. As an example, you quite often get people using backticks instead of <code> in PRs, because people are not used to writing raw HTML. I think this kind of problem would be more common if we asked people to chop and change.

I also think that we don't use notes and warnings too much.

I definitely do think that it is important to consider what the format is like in terms of being able to write tooling support for it. But I think "more difficult" is still OK. "impossible" would be another matter. But I'd expect us to provide "official MDN plugins" for popular code editors at some point anyway.

I suppose I'd like to advise that we try a markdown solution to begin with, and only go with an HTML solution if we really feel that there's no other choice.

[ddbeck]

we ask the reader to break from markdown to using HTML

Ooh, so this is interesting to me, @chrisdavidmills. I didn't see the proposals this way at all (nor Markdown itself, generally). I figured that (a subset of) HTML is a part of Markdown, so (most) HTML is Markdown.

In terms of this actual proposal, I thought were were talking about a structural representation of notes, not a syntax per se. That is, we were trying to find a structural representation which would be ergonomic to read and write using Markdown (including the subset of HTML that GFM tolerates).

Take Option 2 as an example. You could write it three ways, using varying amounts of HTML, to achieve the exact same abstract syntax tree and output HTML:

Example A (Markdown using Markdown-exclusive syntax only)

> ###### Note
> This could be a note

Example B (Markdown using Markdown-exclusive syntax and HTML)

<blockquote>

###### Note
This could be a note.

</blockquote>

Example C (Markdown using HTML only)

<blockquote>
<h6>Note</h6>
<p>This could be a note.</p>
</blockquote>

Output

(from A, B, or C, using pandoc -f gfm)

<blockquote>
<h6>Note</h6>
<p>This could be a note.</p>
</blockquote>

I understood the Option 2 proposal as meaning that any of examples A, B, and C would produce the output HTML and the output HTML is what we would target for styling etc. (though A would be preferred as a matter of source style).

But what I'm hearing is that you want to target a specific source text for notes. That is to say, that only example A could produce valid notes, while B and C would not. This implies that example A would generate some other abstract tree compared to examples B and C and that off-the-shelf Markdown processors would never, by default, produce a valid note.

[chrisdavidmills]

@ddbeck I think what you've written above is very interesting, but now I'm worried that I'm confusing matters more than helping ;-)

To be clear:

• I'm trying to reach consensus on what syntax we should use to represent notes in the MDN markdown source.
• I am of the understanding that this would then be rendered as an HTML note/warning in the final rendered page, just like notes/warning are now.
• I don't think any of the options would provide invalid notes/warnings. I think they are all vlable options.
• I'm merely trying to express my concern that I think we should try to include as little HTML in the markdown source as possible. I think this would make writing the source more difficult than it needs to be.

It sounds to me like we are all on the same page here. Does that clear things up, or am I still misunderstanding some of these points?

[ddbeck]

I don't think there's a misunderstanding exactly, but I am trying to figure out the boundaries of the choice we're trying to make. I guess what I was getting at with my previous comment is this: is option 2 a new syntax that happens to shadow existing Markdown syntax? Or is option 2 plain CommonMark/GFM that will generate a certain kind of representation that we'll transform or post-process?

Or to reframe this question in a way that applies to any of the options: is there magic and, if there is, where does that magic happen?

---

Thinking through this some more, I ended up coming up with examples of options 1, 1a, 2, and 3, showing their typical source syntax, what the abstract representation could be (this also stands in for a generic Markdown to HTML conversion, like you'd get from your editor or pandoc or what have you), and what Yari would yield at the end of the pipeline: https://gist.github.com/ddbeck/eeb8b107a1ca1cdc5ec1d2a893236e6a.

I think that gist illustrates the relative complexity (and also the behavior we haven't defined yet) of the different options, at least as I have already interpreted the options (which is to say, any of the abstract or post-Yari code blocks could be wrong, if I've misunderstood where the magic happens).

[Ryuno-Ki]

I think, I mentioned it towards Peter in some PR before: A markdown interpreter like markdown-it allows for plugins like markdown-it-attrs that would allow for adding attributes / classes to markdown syntax.

I recall having looked up a similar plugin to what was used in Yari back then.

[wbamberg]

Or to reframe this question in a way that applies to any of the options: is there magic and, if there is, where does that magic happen?

There is definitely magic somewhere in option 2, but I'm not sure I really understand the relevance of your distinction between the "Abstract" and "Post Yari". I mean, if we customize the Markdown->HTML for the sake of option 2, that's a part of Yari, isn't it? It's a Yari-specific customization.

There are two main representations that we need to specify as I understand it:

• the syntax people have to write, to get a note box
• the HTML generated by Yari from that source

So (I think - but it's not my proposal) the suggestion for Option 2 is basically:

source syntax:

> **Note**
>
> This is a note.
>
> It's allowed to contain paragraphs and `inline formatting`.

HTML Yari output (could be something like)

<div class="notecard note">

<p class="notecard-title>Note</p>

<p>This is a note.</p>

<p>It's allowed to contain paragraphs and <code>inline formatting</code>.</p>

</div>

I don't think the output should be something like:

<blockquote>

<p>Note</p>

<p>This is a note.</p>

<p>It's allowed to contain paragraphs and <code>inline formatting</code>.</p>

</blockquote>

...because a note is not a quote.

So there is magic, in that there is MDN-specific processing of particular bits of what is apparently GFM syntax.

But maybe I'm wrong? Maybe the idea of option 2 is just to produce something that can be styled to look like a note, but the markup is just a blockquote? That does seem to be what the Gitbook plugin is doing: https://github.com/erixtekila/gitbook-plugin-richquotes/blob/master/index.js.

What I struggle with a bit is:

every instance where we ask the reader to break from markdown to using HTML is a bit of cognitive overloard that we don't want to underestimate.

There is no way to write notes and warnings in GFM. Whatever option you choose, authors have to "break from GFM" and incur the cognitive overhead. Given that, I think the cognitive overhead of a custom element or <div class="note">...</div> is lower than us overloading some specific semantics on some very particular combination of GFM markup and text contents.

But I don't think there's much value in going round this again.

[ddbeck]

@wbamberg

There is definitely magic somewhere in option 2, but I'm not sure I really understand the relevance of your distinction between the "Abstract" and "Post Yari". I mean, if we customize the Markdown->HTML for the sake of option 2, that's a part of Yari, isn't it? It's a Yari-specific customization.

I'm concerned about intermediate representations because it impacts tooling that operates against content before its been run all the way through Yari to production. If I want to write a content linter or customize the appearance of my markdown preview, then it's significant whether a note is, canonically, a <blockquote> or <div class="note">. But it's not necessarily important what specific source produced it (e.g., for <blockquote>, whether a > or a literal <blockquote> tag) or what's ultimately served by the CDN (for which Yari might've minifed the CSS class name or whatever).

I've already staked out my position on which option is best, but if we're going to go with one of the other options, then I'd like it defined in terms that limit the complexity for secondary tooling (assuming we still have consensus that playing nice with non-Yari Markdown tooling is desirable).

[hamishwillee]

I'm only interested in the authoring experience. The > **Note** This is a note. approach to this problem of asides is by far the easiest for people who aren't working in the content every day to use and remember (@wbamberg note that first line can be on the same line as the "Note" text). Probably because it is closest to the markdown philosophy:

Markdown is intended to be as easy-to-read and easy-to-write as is feasible.

This kind of syntax is not so good for translation systems, which are much better at recognizing tags and macro-markup "out of the box". I don't know if that is a factor to consider, because I don't know what system we will be using or its limitations.

Anyway, what do we have to do to head towards some consensus (my understanding of the above discussion is that intermediate and rendering formats can be discussed independently)?

[chrisdavidmills]

I think we are in danger of going round in circles here, so I'd like to propose that we vote on the options, then move forward, Implement a prototype, and test it out. We can always move to a different option if the prototype reveals major flaws. They are not that different from one another.

I still like 2 the best. It requires the least typing, and I am still concerned about having to swap from writing markdown to writing HTML half way through (this is what I really mean by the cognitive overload thing; I didn't explain that very well...)

[sideshowbarker]

I still like 2 the best. It requires the least typing, and I am still concerned about having to swap from writing markdown to writing HTML half way through (this is what I really mean by the cognitive overload thing; I didn't explain that very well...)

I also still strongly prefer 2.

[Ryuno-Ki]

Option 2 looks like the one with the least magic (applying Occam's Razor here).

[hamishwillee]

Option 2. But to very clear I mean the option with the > **Note** and not > ####Note. So:

> **Note** First line of text
>
> Another line of text
> Yet more text

[Ryuno-Ki]

If I see that correctly, @chrisdavidmills, @sideshowbarker, @hamishwillee and me vote for number 2, @ddbeck and @wbamberg for option 1.

I think, the next step thus should be a RFC PR for switching to Option 2 to have the decision formally adapted (especially since some topic review owners didn't cast their voice here.

Do you agree?

[wbamberg]

I think the next step is to file a PR against mdn/content to update https://developer.mozilla.org/en-US/docs/MDN/Contribute/Markdown_in_MDN to describe option 2 as the way we will handle callouts. It also needs to talk about the issues raised in #3927 (i.e. the need to have a version which doesn't set a title). It also needs to talk about the HTML output, and the abstract representation, per Daniel's point above.

I haven't had time to do this yet but I will get to it.

[wbamberg]

I've written this up in #4352.

[wbamberg]

#4352, which updates the Markdown spec, is closed, and I've also updated #3350 (comment), which describes how to convert HTML notes/warnings/callouts into the Markdown format. So I'm closing this one.

[glgoose]

I think, I mentioned it towards Peter in some PR before: A markdown interpreter like markdown-it allows for plugins like markdown-it-attrs that would allow for adding attributes / classes to markdown syntax.

I recall having looked up a similar plugin to what was used in Yari back then.

There is a specific markdown-it plugin for this use-case called markdown-it-container. VuePress uses that same syntax with their Custom Containers

::: warning
This is a warning
:::

So they implement something like a code block syntax mentioned by @hamishwillee in #3483 (comment)

[wbamberg]

@glgoose , thanks! We chose the syntax we did mostly because it looks reasonable in GFM, without any extensions, meaning it's likely to render nicely on GitHub and in most people's editors by default.

I'm open to considering other options, but I think we'd want a good reason why, having just been through this process of choosing a representation.

[glgoose]

@glgoose , thanks! We chose the syntax we did mostly because it looks reasonable in GFM, without any extensions, meaning it's likely to render nicely on GitHub and in most people's editors by default.

I'm open to considering other options, but I think we'd want a good reason why, having just been through this process of choosing a representation.

Given that the current syntax implementation renders nicely on GitHub and since that's where the docs live, it seems like it's a great choice.