[Markdown] Decide what to do about class="hidden"

[wbamberg]

This overlaps a bit with "[Markdown] Decide how to represent code blocks".

In MDN we use class="hidden" to have content that's not displayed. I think there are two categories here:

1. comments: content that's a message to maintainers of the documentation
2. hidden code: pre blocks that we want to participate in a live sample but not be shown to readers

If there are more categories than this it would be great to know about them!

Dealing with comments

The large majority of these are the comments after interactive examples and BCD tables, that say something like:

<div class="hidden">The source for this interactive demo is stored in a GitHub repository.
  If you'd like to contribute to the interactive demo project, please clone <a
    href="https://github.com/mdn/interactive-examples">https://github.com/mdn/interactive-examples</a>
  and send us a pull request.</div>

A small minority are more targeted to particular bits of content.

To deal with comments, the more conservative option is to convert them to HTML comments. It ought to be possible to automate a lot of this, as long as we can reliably distinguish between this kind and the "hidden code" kind.

The less conservative option is just to delete them (or at least, to delete the boilerplate ones that come after interactive examples and BCD tables).

Dealing with hidden code

The obvious suggestion here is to:

1. support hidden comments on code blocks (as discussed in [Markdown] Decide how to represent code blocks #3512)
2. where the hidden attribute is not on a code block directly (for example, it's on a containing <div>, to transfer the attribute from the <div> to any blocks it contains.

This isn't always going to work, though, because as @chrisdavidmills points out in #3512 (comment), we have some live samples where all the sources and the heading are inside <div class="hidden">, and these need some different treatment.

Some numbers

I looked at how many hidden attributes exist in our docs, and in particular:

• how many of them contain code blocks (and are therefore probably part of a live sample)
• how many of them do not (and are therefore probably just comments)

Hidden elements that don't contain code blocks (probably comments):

learn -     1
mdn -       8
mozilla - 779 - inflated by lots of Chrome acknowledgements in the WebExtensions docs
web -    1573
    accessibility -   1
    api -           595
    css -           234
    guide -           2
    html -          165
    http -          134
    javascript -    434
    manifest -        1
    media -           1
    security -        2
    svg -             3
    web_components -  1
    xslt -            1

Total: 2361

Hidden elements that do contain code blocks (probably live samples):

games -    2
glossary - 8
learn -   94
mdn -      4
mozilla -  2
web -    760
    accessibility -   4
    api -           165
    css -           321  (89 in one page)
    guide -           2
    html -           56
    javascript -      2
    svg -           208
    web_components -  2

Total: 870

This is pretty much what we might expect. It would be worth analysing the hidden-code group more deeply to see if many of them seem to be automatically fixable.

As far as the JS docs are concerned, almost all the uses of hidden are for comments. I dug a bit more deeply into this, and almost all of the comments (all except 20-30) are associated with BCD or interactive examples. One nice thing about this is that we can convert to HTML comments in advance of a Markdown conversion.

[chrisdavidmills]

Quick thoughts here:

1. I think we can just remove hidden comments for source editors. The content and associated documentation should be intuitive enough that we don't need this. For the Chrome acknowledgements, would it hurt us to just have the acknowledgement visible somewhere at the bototm of the page?
2. I still think it'd be good to support hidden code blocks via a hidden class put on the code fence.
3. I wonder how many of the instances you found we of the type I brough up, where a hidden div is use to hide a code block, plus a heading, that kind of thing? In those cases, could we not just convert them t use github embedded samples rather than regular ones? If there's not too many?

[wbamberg]

1. I think we can just remove hidden comments for source editors. The content and associated documentation should be intuitive enough that we don't need this.

👍 I filed #3755 to do this in the JS docs.

[Ryuno-Ki]

Since #3512 is closed now, it might be worth looking at this again.

For the code block comments, I assume, it contains content we want to keep. Perhaps worth already converting them to HTML comments (via the element that got hidden?) and fill a PR so we can omit them from the consideration here.

[wbamberg]

I think there are a couple of things we need before this is closed.

(1) a resolution on what this means for our our "MDN Markdown" spec. I think this part is done in #3512, and recorded at https://developer.mozilla.org/en-US/docs/MDN/Contribute/Markdown_in_MDN#example_code_blocks

(2) a resolution on what our conversion process from HTML to Markdown should look like. I think this part is not yet done but could look something like:

• if an element has class="hidden"
  • if it's a div with an ID, and contains code blocks
    • if it contains only code blocks, transfer the "hidden" class to the code blocks, and discard the outer element (but keep the code blocks)
    • otherwise, flag this as an unconvertible structure for the humans to sort out manually
  • otherwise, discard the element and its contents

A simpler and possibly safer version, which involves more manual work:

• if an element has class="hidden"
  • if it's a div with an ID, and contains code blocks, flag this as an unconvertible structure for the humans to sort out
  • otherwise, discard the element and its contents

[wbamberg]

I just updated #3350 (comment) with a description of what the converter should do with class="hidden", so I think we can close this now.