Let's reorganize the CSS docs

[wbamberg]

The structure of the CSS documentation isn't very clear. I think it its original conception the docs had a (completely?) flat directory structure, and macros relied entirely on tags to organize them. Over time subdirectories have been added, but it's still mostly flat.

In general this makes it hard to see what we have, or how our docs are organized. Which module pages do we have? Which are missing? Which CSS function pages do we have? It's hard to get a quick answer to this.

It also causes specific problems when features in different parts of the language have the same name. For example, we have the color property and the <color> data type: because they have the same (normalized) name, we have to have a _value suffix on the data type:

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

Not all data types get this suffix, only those that happen to have another language feature that has the same name:

https://developer.mozilla.org/en-US/docs/Web/CSS/image <- no suffix
https://developer.mozilla.org/en-US/docs/Web/CSS/position_value <- oops, need a suffix!

Similarly we have the fit-content keyword and the fit-content() function:

https://developer.mozilla.org/en-US/docs/web/css/fit-content
https://developer.mozilla.org/en-US/docs/web/css/fit-content_function

...and again it is hard to predict which functions will get the _function suffix.

Proposal

To begin with I'd like to propose the following hierarchy, based on (but slightly simplifying) the set of CSS page types: https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/Page_type_key#css_page_types

css/reference
    /at-rules (with descriptors underneath their at-rule, and media features under @media)
    /combinators? or should they be under selectors?
    /functions
    /keywords
    /modules
    /properties
    /selectors (including pseudo-classes and pseudo-elements)
    /types

The rest of the pages are all guide pages or landing pages, and could stay where they are (there is often a sensible hierarchy there already, e.g. https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flexible_Box_Layout#guides).

We'd have to figure out how to update all the macros so this still works. In particular this would break cssxref.

[schalkneethling]

Tagging @mdn/yari-content

[SphinxKnight]

cc @mdn/localization-team-leads since such a move might trigger a large number of "sync translated-content" PRs

[teoli2003]

I like the idea to have a less flat hierarchy (with @Elchi3, we were able to unflatten a bit the API almost a decade ago).

We'd have to figure out how to update all the macros so this still works. In particular this would break cssxref.

I'm worried here that while trying to solve the unpredictability of adding _value or _function, we are instead adding complexity for every link by breaking {{cssxref}} (Replacing complexity for a few by complexity for all).

I can imagine fairly easy solutions for sidebar macros, but how do you plan to use {{cssxref}} in this new world?

I think you are right that this is the key problem, but what would be the solution? Immediately, I can see two:

• removing cssxref and using Markdown links,
• adding a parameter, optional unless there is ambiguity

The first one means any author needs to know the hierarchy, the second one is _function, or _value in disguise.

Maybe there are more solutions to consider here…

(I would like to avoid the complexity of jsxref, where rather to find the right parameter set, I prefer to use a Markdown link instead)

[teoli2003]

My opinion (feeling?) is that we should eliminate all link macros.

But we should do it with an additional change: instead of using the production links (/en-US/docs/X/Y/Z), we should use the GitHub links (/files/en-us/x/y/z), and Yari should replace them with the production links (using the slug in the document).

That way, we can navigate inside the GitHub UI, and more importantly, the content code becomes more independent of the production site structure.

I'm not saying we should do it now, just that I'm ok with getting rid of cssxref (and jsxref).

The link macros were created because it was difficult to style links correctly in an HTML-storage world, not because the URL was difficult (The information architecture was almost an all-flat hierarchy back then). This reason disappeared with our migration to Markdown.

[Graywolf9]

It looks like

1st: change cssxref("position") to cssxref("types/position") could be the direct solution for the main problem: reorganize
2nd: consider the migration of link macros to markdown urls
3rd: change the url from /lang/docs/ to /files/lang/

[wbamberg]

My opinion (feeling?) is that we should eliminate all link macros.

💯

But we should do it with an additional change: instead of using the production links (/en-US/docs/X/Y/Z), we should use the GitHub links (/files/en-us/x/y/z), and Yari should replace them with the production links (using the slug in the document).

That sounds like a good idea.

[OnkarRuikar]

That way, we can navigate inside the GitHub UI, and more importantly, the content code becomes more independent of the production site structure.

Also, it will be easy to create links using intellisense of IDEs:

[teoli2003]

Yes, "intellisense" of VSCode just got better. It would be great to use the "generic" tools that IDE makers build in their products.

[rachelandrew]

I'd probably suggest grouping some of this under /values, these seem all to be values (see https://www.w3.org/TR/css-values-4/)

• keywords
• functions
• types

Seems a bit odd to not group them as values, granted that doesn't help with fit-content, but I think that's a bit of an exception. It would fix issues such as color (property) and <color> (value).

Combinators are selectors, and so should be included with selectors.

[wbamberg]

The organization I proposed really just reflects how we already implicitly categorize things on MDN at the moment. We already talk about "CSS data types" and "CSS functions" as different kinds of thing, and use different notation for them, and (implicitly, but should explicitly) have different page structures for them, and have different landing pages for them (functions, types). So it's just making that distinction more visible.

But if this is misleading I'm happy to have alternatives. It seems like a pity to go to all this work and not fix the naming collisions issue though.

[wbamberg]

One thing we might do is have "values" and then the different value types underneath them:

css
   /reference
             /values
                    /functions
                    /keywords
                    /types

...which is intended to reflect https://www.w3.org/TR/css-values-4/#component-types , except for:

• point 3, which is covered by "properties"
• point 5, which AIUI includes things like <baseline-position> in https://developer.mozilla.org/en-US/docs/Web/CSS/justify-items#formal_syntax, and which usually don't get separate pages (when they do we call them "type").

[ramiy]

Related: mdn/browser-compat-data#10563

[Rumyra]

I really like this idea @wbamberg - thank you - and I agree with the proposed grouping.

It's slightly out of scope of the original discussion, but I also like @teoli2003 suggestion for replacing xref stuff with github links, I think we're getting to the stage where it's starting to make sense to have markdown links over the macros. However this should be considered as a separate task and a discussion that should involve @mdn/core-dev

Aside - we're starting work on a roadmap at the moment, so I'm going to reference this in that work

[teoli2003]

Moving away from the xref macros and having GitHub links could potentially be a joint MDN-OWD goal for 2023. (We would need a plan because it touches Yari, Kuma macros, and the content and we need to be careful)

[Josh-Cena]

Deprecating xrefs makes the source much longer, because I use the source text's length to roughly control the length of each paragraph. We could limit its use (for example, jsxref has four arguments but I only ever use the first two; we shouldn't allow HTML markup in the macro), but I find writing {{jsxref("Object.keys()")}} much more enjoyable than copying the long URL or file path and inevitably duplicating the names Object/keys (once in link text, once in link target).

[estelle]

css/
    /atrules
          /font-face/ (css-at-rule-descriptor pages related to font-face go here, other css-at-rule-descriptor pages nested similarly)
          /media/ (css-media-feature pages go here)
    /functions (only a few, if any, `css-function` pages; possibly the trig functions?)
    /guides     (`guide`, `css-guides` and `landing-pages`, none nested, unless it is a literal series with back and next buttons)
    /keywords (some `css-type` pages; anything writing without `<>` that doesn't fall under a `<>` type; ncluding flags, some guide pages (like actual-value), ident, etc)
    /modules (`css-module`.  currently some are listed as `guide`, but won' t be next quarter)
    /properties    (`css-property` and `css-shorthand-property`)
    /selectors    (`css-pseudo-class`, `css-pseudo-element`, `css-combinator`)
    /types     (`css-type`, anything written as `<css-type>`)
           /image
                 /gradient  (gradient `css-function` pages go here)
                 /image-set
          /filter (the 10 or so filter css-function pages go here
          /blendmode (the 16 or so css-function blend modes go here)
          /color/ 

I don't know where custom properties would go.
Would customColor go under color or keywords?

Note there are very few functions, if any, are under /function. Rather, functions are under their 'type'.
no dashes in blendmode, atrule, etc. dashes only in property names or keywords as written in CSS as a value.

[ramiy]

We have two different function types:

• CSS value functions - https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Functions
• CSS at-rule functions - https://developer.mozilla.org/en-US/docs/Web/CSS/At-rule-functions

Two different types of functions. I don't think we should mix them because there are identical function names.

[ramiy]

    /types     (`css-type`, anything written as `<css-type>`)
           /image
                 /gradient  (gradient `css-function` pages go here)
                 /image-set
          /filter (the 10 or so filter css-function pages go here
          /blendmode (the 16 or so css-function blend modes go here)
          /color/ 

I think that we need to move all the image, filter, blendmode, color to simple functions.

[estelle]

Been thinking about this. and looking forward to it.

-- /CSS/
   --  /descriptors/  
   --  /language/ 
   --  /modules/
   --  /properties/
   --  /selection/ (or /selectors/) 
   --  /values/  

with prefixed features nested in subdirectories, so:

-- /CSS/
   --  /descriptors/  
   --  /language/ 
   --  /modules/
   --  /properties/
       -- /prefixed/
   --  /selection/ (or /selectors/) 
       -- /prefixed/
   --  /values/  
       -- /prefixed/

where:

• descriptors includes css-at-rule and nested css-at-rule-descriptor. example:

   --  /descriptors/  
        -- /font/
             -- /font-family/
             -- /unicode-range/

• language includes concepts, currently guides, like syntax, block formatting content, box model, used value, etc)
• modules includes all the css_xxx files. Subdirectories include guides.
• properties includescss-property and css-shorthand-property
• selection includes everything that comes before the {} in a selector block, includingcss-pseudo-class, css-pseudo-element, css-combinators)
• values includes data types along with their keywords and functions. Includes css-type, many css-functions, and keywords, like initial, which are currently guides.

   --  /values/    
        -- /image
             -- /gradient  (gradient `css-function` pages go here or nested further)
             -- /image-set
        -- /filter/ (the <data-type>)
             -- /sepia/ (the `css-function`s of that type)
        -- /color/ 

There should NOT be a top-level function directory, as function notation is found in selectors and values