[Markdown] Decide what to do about class="button" and class="callout"

[wbamberg]

The Guide to classes and styles used in MDN content lists button as a class you can apply, but callout isn't documented. Nevertheless these often go together so let's look at them together.

• button makes a link look like a button
• callout makes a fancy blue box

See the "Looking to become a front-end web developer?" bit at the start of https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout for a callout containing a button.

So it turns out that across all of files/en-us, all instances of callout contain a button, and specifically are this "Looking to become a front-end web developer?". That includes the following pages:

/content/files/en-us/learn/accessibility/index.html
/content/files/en-us/learn/css/building_blocks/index.html
/content/files/en-us/learn/css/css_layout/index.html
/content/files/en-us/learn/css/first_steps/index.html
/content/files/en-us/learn/css/index.html
/content/files/en-us/learn/css/styling_text/index.html
/content/files/en-us/learn/forms/index.html
/content/files/en-us/learn/html/index.html
/content/files/en-us/learn/html/introduction_to_html/index.html
/content/files/en-us/learn/html/multimedia_and_embedding/index.html
/content/files/en-us/learn/html/tables/index.html
/content/files/en-us/learn/index.html
/content/files/en-us/learn/javascript/asynchronous/index.html
/content/files/en-us/learn/javascript/building_blocks/index.html
/content/files/en-us/learn/javascript/client-side_web_apis/index.html
/content/files/en-us/learn/javascript/first_steps/index.html
/content/files/en-us/learn/javascript/index.html
/content/files/en-us/learn/javascript/objects/index.html
/content/files/en-us/learn/tools_and_testing/client-side_javascript_frameworks/index.html
/content/files/en-us/learn/tools_and_testing/cross_browser_testing/index.html
/content/files/en-us/learn/tools_and_testing/github/index.html
/content/files/en-us/learn/tools_and_testing/index.html
/content/files/en-us/learn/tools_and_testing/understanding_client-side_tools/index.html
/content/files/en-us/web/css/index.html
/content/files/en-us/web/html/index.html
/content/files/en-us/web/javascript/index.html

All Learn, except for the main pages in HTML, CSS, JS.

There are only a handful of other instances of button:

/content/files/en-us/mdn/guidelines/css_style_guide/index.html 
/content/files/en-us/web/api/web_audio_api/using_audioworklet/index.html
/content/files/en-us/web/api/web_audio_api/using_audioworklet/index.html
/content/files/en-us/web/api/web_audio_api/using_audioworklet/index.html
/content/files/en-us/web/svg/applying_svg_effects_to_html_content/index.html
/content/files/en-us/web/svg/namespaces_crash_course/example/index.html

What should we do with them?

The "Looking to become a front-end web developer?" seems like a really good case for a KS macro. Then we can generate whatever markup we like. The only alternative might be to have something more native-Yari, like the soapbox thing: so Yari could decide which pages should get this banner and the content doesn't have to know about it. But that seems like a lot more work.

The remaining button instances can be disposed of fairly easily:

/content/files/en-us/mdn/guidelines/css_style_guide/index.html

-> this is actually documentation for button, so when that goes, this can.

/content/files/en-us/web/api/web_audio_api/using_audioworklet/index.html
/content/files/en-us/web/api/web_audio_api/using_audioworklet/index.html
/content/files/en-us/web/api/web_audio_api/using_audioworklet/index.html

-> these should all be links

/content/files/en-us/web/svg/applying_svg_effects_to_html_content/index.html

-> this is in a display: none element and should I think be removed entirely

/content/files/en-us/web/svg/namespaces_crash_course/example/index.html

-> this should be a link

[chrisdavidmills]

I'd personally be happy to do without the button class. As you say, in most cases we can get rid of these or make them into links. In the callout boxes, we can use links instead of a button too.

I do see the need for the ability to have some kind of inline callout, rather than just an overall banner attached to the top of the page. Although I do wonder whether we couldn't just use the same kind of approach for these as for the note and warning boxes...whatever we end up choosing. We could even just use notes for these....? The main issue there would be one of semantic difference, and I'm not convinced that really matters.

[wbamberg]

Although I do wonder whether we couldn't just use the same kind of approach for these as for the note and warning boxes...whatever we end up choosing. We could even just use notes for these....? The main issue there would be one of semantic difference, and I'm not convinced that really matters.

Yeah, that seems like a good idea, especially since these are really all the same kind of thing.

A problem with using the note/warning thing, if we go with the blockquote option from #3483 (comment), is that this option uses the magic word "Note:" to know that this isn't just a blockquote, but is a note callout. But in that case Yari also renders the "Note:" text. But in this case we probably don't want to render "Note:", we just want the callout styling. So: how can Yari understand that this is to be rendered as a callout, but without including the magic word? Or maybe it is OK to include "Note:" for cases like this?

[hamishwillee]

So: how can Yari understand that this is to be rendered as a callout, but without including the magic word? Or maybe it is OK to include "Note:" for cases like this?

Why not another prefix for a box that doesn't render the text, or which allows you to specify the text to be rendered?. After all, we get to define the rules on things that are non-standard.

[chrisdavidmills]

So: how can Yari understand that this is to be rendered as a callout, but without including the magic word? Or maybe it is OK to include "Note:" for cases like this?

Why not another prefix for a box that doesn't render the text, or which allows you to specify the text to be rendered?. After all, we get to define the rules on things that are non-standard.

Yeah, we could just include something for a general callout like

> ###### Callout: Looking to become a front-end web developer?
>
> Content

To produce a callout box with a specific heading, or

> ###### Callout
>
> Content

To produce a callout with no heading...?

[wbamberg]

#4352, which updates the Markdown spec for callouts, is closed, and I've also updated #3350 (comment), which describes how to convert HTML callouts into the Markdown format.

I've also replaced button in our docs with links, so we will treat class="button" as an error in future.

So I'm closing this issue.