CSS items should only belong to a single group
Nobody has claimed this yet.
- 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 —groupsshould 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:
- clean the data so the
groupsarray contains only one group. This would fix the sidebars, while not breaking any client which expectsgroupsto be an array. - add a new property
modulewhich is a single string, and deprecategroups. - update any code that uses
groups, to usemoduleinstead - remove
groups
What do you think?
- do you think only having one "group" is a good change?
- do you currently use
groups, and if so, are you able to update?
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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