mdn / mdn/data

CSS items should only belong to a single group

Open
#238 8 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

idle question
Dominant language
JavaScript
Stars
787
Forks
216
Avg merge
1d 5h
Merged PRs (30d)
6

Description

@rachelandrew is working on sorting out the MDN docs on grid/flexbox/box alignment, and pointed out that the sidebars for these items don't make sense. It seems that part of the reason for this is that some of these items are marked as belonging to multiple "groups" in the metadata. I'd like to propose that we change the data so as to only allow an item to belong to a single group.


CSS data contains a property groups. The docs say:

groups (array of unique strings with at least 1 entry): CSS is organized in modules like "CSS Fonts" or "CSS Animations". MDN organizes features in these groups as well — groups should contain the name of the module(s) the property is defined in.

In most cases, groups only contains a single item, but in a few cases it contains more than one. For example, break-after:

"groups": [
    "CSS Columns",
    "CSS Fragmentation",
    "CSS Regions"
]

Unfortunately the macro used to build CSS sidebars on MDN, CSSRef.efs, isn't very good at dealing with this situation, and the sidebars tend to come out incoherent. Here's the structure of the sidebar for column-gap, with annotations to show its problems:

    CSS
    CSS Reference
    CSS Columns                                  <- this menu item has no children
    CSS Box Alignment
    -> Guides
        -> Using multi-column layouts            <- this should not be under box alignment
        -> Box Alignment In Grid Layout
        -> Box Alignment in Flexbox
        -> Box Alignment in Multi-column Layout
    -> Properties
        -> break-after
        -> break-before                          <- this should not be under box alignment, but it's here because of [this](https://github.com/mdn/data/blob/master/css/properties.json#L3315)
    ...
        -> column-count                          <- neither should this
    ...
        -> column-gap (grid-column-gap)
    ...

We could fix the macro here to handle multiple group better, but I'm starting to think that we would be better to say an item can only belong to a single group. If an item can only belong to one group, then the semantics are clear: it belongs to the group (aka module) whose spec currently defines it. If its definition moves from one spec to another (as, for example, align-items moving from flexbox to box alignment) then the group changes.

We could do this in the following stages:

  1. clean the data so the groups array contains only one group. This would fix the sidebars, while not breaking any client which expects groups to be an array.
  2. add a new property module which is a single string, and deprecate groups.
  3. update any code that uses groups, to use module instead
  4. remove groups

What do you think?

  1. do you think only having one "group" is a good change?
  2. do you currently use groups, and if so, are you able to update?

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing css/properties.json and the documented groups property in css/properties.md, then inspect how CSSRef.ejs consumes group data. First resolve whether the single-group model and staged migration are accepted; completion would require the agreed data and consumer changes without incoherent CSS sidebars.

Written by the indexing model from the issue text.

Assessment

Tech stack
css, javascript
Domain
documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.