[Markdown] class attributes in JavaScript documentation

[wbamberg]

(meta: this isn't really an issue but I wasn't sure where else to put it.)

For converting MDN into Markdown, I thought it would be interesting to look at all the places in our content (JS only, for now) where we use class attributes, since that's a good indication that our content is doing things that will require special attention in Markdown-land.

To get a list, I just did this: grep -r "class=\"" ./files/en-us/web/javascript/ - perhaps there's a better way? :)

Anyway, I got 5906 results there, and this post is going to summarise and classify them.

Code samples

This is the biggest group of changes, comprising 3305 for <pre class="brush: js" alone. It includes the following (numbers after the class, where given, are the number of occurrences):

• brush:
• language identifiers for syntax highlighting:
  • js
  • css
  • html
  • json
  • java (an error)
  • cpp
  • bash
  • plain
• various other instructions:
  • example-good (144)
  • example-bad (206)
  • highlight[...] (23)
  • line-numbers (3)
  • no-line-numbers (9)

Also some invalid variations on these, like brush:js, brush: js; and so on.

Hidden content

This is the class="hidden" attribute. Usually, as expected, this is for the little notes under interactive examples and compat tables. For instance, we get 343 hits for <div class="hidden">The source for this interactive example.. There are a few instances where it's used to give specific advice to maintainers:

<div class="hidden">The following section is also duplicated on ...
<div class="hidden">CAUTION: if you edit this page, ...
<p class="hidden"><strong>TODO</strong>: ...
<div class="hidden">If you are looking to contribute to this document, please also edit ...

I don't see any hidden code blocks, which is the only case where we definitely need to support hidden content.

Notes and warnings

As expected, there are a few different combinations of classes used for noted and warnings:

• notecard
• note
• warning

In total there are about 250 of these.

Tables

There are two classes relating to tables:

• fullwidth-table
• standard-table (the vast majority, 857 cases, presumably almost all spec tables)

...and 46 occurrences of <th class="header", which doesn't appear to do anything?

But this does remind me that GFM tables are much more limited than HTML tables.

Summary markup

I count 102 instances of seoSummary and 25 of just summary. Given how rarely this is applied I don't think we need to worry about supporting it.

Columns

I count 6 instances of twocolumns and 7 of threecolumns. They don't seem to have any effect.

Miscellaneous

There are quite a few classes that are each used in just a few places, and that I think we could remove.

• message-body-wrapper
• message-flex-body
• devtools-monospace
• message-body
• external
• external-icon
• internal
• notranslate
• name
• blob-code-inner
• blob-code-marker
• eval
• gtx-trans-icon
• objectBox
• objectBox-string
• link-https
• syntaxbox
• example
• objectBox
• objectBox-number
• callout
• pl-s
• noinclude
• button
• primary
• example-4
• mw-redirect
• highlight-span
• highlight-spanned
• short_text

[jpmedley]

Without going into too much detail, some of these issues can be dealt with in the selection of markdown processor and extensions. web.dev specifies a language on the first line of a code block (scroll down).

[teoli2003]

Just for the record, there is also the class "index" that allows multicolumn lists like in https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Box_Model (there is a display bug with it, that's why I noticed it).

[wbamberg]

Just for the record, there is also the class "index" that allows multicolumn lists like in https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Box_Model (there is a display bug with it, that's why I noticed it).

Yes, not in JS though. It is my hope that we can stop doing this in authored content (and that the fact that JS doesn't need it can be an argument that none of our other docs do).

[sideshowbarker]

I propose we move this to the Discussions tracker.