[Markdown] Decide what to do about `<div class="index">` #579

wbamberg · 2021-07-25T23:59:11Z

wbamberg
Jul 25, 2021
Maintainer

The CSS documentation sometimes uses markup like <div class="index">.... This gets you a multi-column layout, like this:

Where it is used

There are 50 pages under /CSS that use this feature.

See the complete list here.

Almost all pages that use this are "module pages" - pages that provide an overview of a particular CSS module - where they want to list all the properties in that module in a "Reference" section. For example: https://developer.mozilla.org/en-US/docs/Web/CSS/css_overflow#reference .

There are just a few that aren't:

These three:

https://developer.mozilla.org/en-US/docs/Web/CSS/css_box_alignment/box_alignment_in_flexbox
https://developer.mozilla.org/en-US/docs/Web/CSS/css_box_alignment/box_alignment_in_grid_layout
https://developer.mozilla.org/en-US/docs/Web/CSS/css_box_alignment/box_alignment_in_multi-column_layout

...are subpages of the "CSS Box Alignment" module page, and describe aspects of the module particular to each layout type. I think (but not sure) that the lists of properties they contain should duplicate the list in the main "CSS Box Alignment" module page.

These three:

https://developer.mozilla.org/en-US/docs/Web/CSS/microsoft_extensions
https://developer.mozilla.org/en-US/docs/Web/CSS/mozilla_extensions
https://developer.mozilla.org/en-US/docs/Web/CSS/webkit_extensions

...list proprietary extensions to CSS.

Then there are a few miscellaneous overview pages:

https://developer.mozilla.org/en-US/docs/Web/CSS/at-rule
https://developer.mozilla.org/en-US/docs/Web/CSS/css_functions
https://developer.mozilla.org/en-US/docs/Web/CSS/css_miscellaneous

What should we do with it?

I can think of three main options:

stop supporting it, and list the properties in a simple <ul> in one column
write a macro that supports it in module pages, and remove it in other places
support it by having it included as HTML

Stop supporting it

I'd vote for this option. Apart from a general principle of wanting to simplify things, there are a couple of other arguments:

the JS docs (~900 pages) don't need this layout option, and they're generally reckoned to be a particularly high-quality part of MDN. Why is CSS different? Even Web/API only uses it 20 times in 6000 pages.
in most cases there aren't many items to list, and in those cases multi-column looks quite weird: https://developer.mozilla.org/en-US/docs/Web/CSS/css_lists_and_counters#properties. A single column would be better here.
even where there are many items https://developer.mozilla.org/en-US/docs/Web/CSS/css_backgrounds_and_borders#css_properties it's not clear to me that a multi-column list is easier to scan, because you have to think about which column the item you are looking for is in.

Use a macro

I believe that this would be reasonably practical. mdn/data has a "groups" item for each property (e.g. https://github.com/mdn/data/blob/master/css/properties.json#L2046), so we could write a macro that takes a group name as a parameter and renders a list of the properties in that group. This would be better than the current situation where the lists are maintained by hand.

Because the macro emits HTML, it can emit <div class="index"> and get the fancy layout.

We've started to talk about using webref instead of mdn/data, but we could probably switch to using webref easily enough in the future.

Support it as HTML

This would be my least favourite option.

Answered by wbamberg

Aug 9, 2021

Thanks for everyone's thought on this! I just filed mdn/content#7726 to remove <div class="index"> from the CSS documentation, and Hamish merged. So we can also close this discussion.

I do think for the module overview pages a macro is the correct option, but as far as Markdown is concerned removing them is just as good.

View full answer

hamishwillee · 2021-07-26T06:33:06Z

hamishwillee
Jul 26, 2021

My 2 bits:

I prefer single column list for small lists, and I'd change them irrespective of what we decide to do about this syntax.
For those larger lists I disagree that they are less useful or odd looking. It is frustrating to have very long lists, particularly if there is content on the other side you are interested in.
I tend towards the idea of using macros to generate this kind of thing - either from data or subdirectory levels.
Agree HTML not a good plan.

I suspect JS must have large lists of properties too. Are there any cases to compare against?

4 replies

teoli2003 Jul 26, 2021

I agree with Hamish here:

HTML is not a good plan
Small lists should be single column (E.g. https://developer.mozilla.org/en-US/docs/Glossary/Flex_item or https://developer.mozilla.org/en-US/docs/Web/API/Sensor and most other API overview pages)
A few long lists are better in multicolumn.

As the name of the class says, the index class was created for large indices and not for creating multicolumn lists.
{{CSS_Ref}}, {{ListGroups}}, and {{APIListAlpha}} are a few macros using them. Most of the time these macros are used only once. They exists as indices need to be automatically generated to be kept up-to-date.

If we remove the use of class="index" for small lists, and keep it in these macros, I think we will be left with very few cases. We could then discuss what to do with each of them.

Here is one example: https://developer.mozilla.org/en-US/docs/Web/API/PerformanceEventTiming

In other words, lets keep index for actual indices (and generated in macros); use simple lists or definition lists for the small list use case; and handle case by case the remaining ones.

wbamberg Jul 27, 2021
Maintainer Author

Thanks for the views!

Cases inside macros are not a problem for Markdown of course. The cases listed here are all outside macros, and the ones with the longest lists are the proprietary CSS ones:

https://developer.mozilla.org/en-US/docs/Web/CSS/microsoft_extensions
https://developer.mozilla.org/en-US/docs/Web/CSS/mozilla_extensions
https://developer.mozilla.org/en-US/docs/Web/CSS/webkit_extensions

After that are some of the bigger modules, like:

https://developer.mozilla.org/en-US/docs/Web/CSS/css_backgrounds_and_borders

There's also:

https://developer.mozilla.org/en-US/docs/Web/CSS/css_functions

...but that's weird because it lists all the functions twice, once separate by area and once in a single big index. I question the value of that.

So for pages like these, the question is still, do we live with single-col or write a macro? One complicating factor is that while it would probably be quite easy to write a macro that lists all properties belonging to a given (mdn/data) group, that won't work for much of https://developer.mozilla.org/en-US/docs/Web/CSS/mozilla_extensions , which wants to list all kinds of things in this way (including, for example, lists of values that various properties can accept).

Ryuno-Ki Jul 27, 2021

I vote for single-column.
We can avoid issues like https://github.com/mdn/mdn-minimalist/issues/682 this way easily.

wbamberg Jul 27, 2021
Maintainer Author

Yeah, there are definitely issues with the way multicol is implemented on MDN at the moment (also here: https://developer.mozilla.org/en-US/docs/Web/CSS/Mozilla_Extensions#mozilla-only_properties_and_pseudo-classes_avoid_using_on_websites the layout is broken and the whole page scrolls). Of course these kinds of things are fixable but I'm always on team keep it simple.

rachelandrew · 2021-07-27T03:46:54Z

rachelandrew
Jul 27, 2021

I'd be happy with these being a single column. I also wanted to remove the duplication on that CSS Functions page a while ago, I can't remember why that suggestion was outvoted, but I have never thought the index that useful and it's a pain to keep updated.

Background and Borders could probably do with an update, it doesn't include the flow relative mappings, which it probably should. I wonder whether I could reformat that list into groups, thus making it not just a long list anyway.

If the above sounds ok, I could deal with those by removing the duplication on CSS Functions, and reformatting backgrounds and borders to be hopefully also more useful.

I'm not sure whatr to suggest with those extensions pages, there was another issue raised about those yesterday too. Maybe they need looking at more generally.

1 reply

wbamberg Jul 27, 2021
Maintainer Author

Thanks Rachel!

If the above sounds ok

That all sounds great to me!

I'm not sure whatr to suggest with those extensions pages, there was another issue raised about those yesterday too. Maybe they need looking at more generally.

Yes, I'm not sure either. I'm not sure they are terribly useful pages, and as you said in the other bug they don't seem fully up to date. Maybe it would be OK to single-column them for the time being?

hamishwillee · 2021-07-27T22:28:50Z

hamishwillee
Jul 27, 2021

No need to guess. From this PR see what single-column would look like for some of these cases:

My take on this is that the compact view is better, but I can live with the single column (obviously some tidy up required - I just removed the divs)

2 replies

wbamberg Jul 27, 2021
Maintainer Author

Thank you Hamish! I guess it's subjective and I am biased by wanting to keep things simple, but I think it looks all right. And there are places where single-column is much more scannable than multi, such as:

https://pr7361.content.dev.mdn.mozit.cloud/en-US/docs/Web/CSS/Mozilla_Extensions#formerly_proprietary_properties_that_are_now_standard

versus

https://developer.mozilla.org/en-US/docs/Web/CSS/Mozilla_Extensions#formerly_proprietary_properties_that_are_now_standard

hamishwillee Aug 2, 2021

I think you can go ahead with your plan - option 1 to remove the class that forces lists to be multi-column. Certainly the few cases where I prefer the compact view are not worth the complexity, and might be addressed on case by case basis.

wbamberg · 2021-08-09T01:27:35Z

wbamberg
Aug 9, 2021
Maintainer Author

Thanks for everyone's thought on this! I just filed mdn/content#7726 to remove <div class="index"> from the CSS documentation, and Hamish merged. So we can also close this discussion.

I do think for the module overview pages a macro is the correct option, but as far as Markdown is concerned removing them is just as good.

1 reply

hamishwillee Aug 9, 2021

It certainly looks either better or as good for all the cases you fixed in 7726. I checked :-)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

MDN Web Docs

[Markdown] Decide what to do about `<div class="index">` #579

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Replies: 0 comments 12 replies

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

Select a reply

[Markdown] Decide what to do about <div class="index"> #579

wbamberg Jul 25, 2021 Maintainer

Where it is used

What should we do with it?

Stop supporting it

Use a macro

Support it as HTML

Replies: 0 comments · 12 replies

wbamberg Jul 27, 2021 Maintainer Author

wbamberg Jul 27, 2021 Maintainer Author

wbamberg Jul 27, 2021 Maintainer Author

wbamberg Jul 27, 2021 Maintainer Author

wbamberg Aug 9, 2021 Maintainer Author

[Markdown] Decide what to do about `<div class="index">` #579

wbamberg
Jul 25, 2021
Maintainer

Replies: 0 comments 12 replies

wbamberg Jul 27, 2021
Maintainer Author

wbamberg Jul 27, 2021
Maintainer Author

wbamberg Jul 27, 2021
Maintainer Author

wbamberg Jul 27, 2021
Maintainer Author

wbamberg
Aug 9, 2021
Maintainer Author