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

[dipikabh]

Hi all, thanks to everyone who attended the Editorial on May 12 and shared initial thoughts on the CSS reorganization plan. It is based on the proposal shared in this discussion and takes into account other comments shared so far.

This is a Google Sheets file. For anyone interested in this topic, please request access to the file. You're welcome to add a tab to the sheet to share your feedback, suggestions, questions, or concerns. Or you can share your comments here. We're aiming to collect all the feedback over the next few weeks before finalizing the folder structure.

(For a quick visual of the proposed structure, I’ve also shared a preliminary tree layout here: https://gist.github.com/dipikabh/5b5f5be5ad2ce0eaf470bf48915cf186)

[chrisdavidmills]

Overall, I really like the proposed CSS reorg tree, @dipikabh. It certainly organizes everything much better and makes it easier to find existing pages you want to work on, or new pages you want to figure out where to put. I appreciate the addition of a specific how-tos section for locating pure task-based guides that potentially span across modules.

I agree with most of the choices you've made here. I did have a few queries and points:

1. I think this was asked before, but — I'm assuming you are intending that we will have a landing page for each directory, e.g., types, keywords, at-rules, reference, guides? I would be in favor of this, but I also think we should look for ways to automate them where possible, at least partially. For example, the CSS functions index page is currently a bit annoying because every time you add a new function, you have to add it to this page, in two places, manually.

2. What do you envisage going in tutorials, as opposed to guides? In my mind, "how to use this feature" articles inside topics (like CSS, JS, APIs, HTML, etc.) would mostly take the form of guides, and tutorials would be aimed more at beginners to introduce them to an overall topic area. In the case of HTML, CSS, and JS/APIs at least, the learn web development area of the site provides this function, and we'd need to be wary of duplication. Unless, of course, in these cases, the tutorials section would just link to the learn tutorials?

3. I think the most controversial part of this is going to be moving the guides under a separate guides section versus keeping them under their respective module pages, especially considering @estelle just did a bunch of work moving them under modules ;-) What is best for the user and the site authors, I think, depends on how intuitive each approach is.

Do people naturally think of CSS topics per module, or per use case? I think the two are sometimes the same (for example, filter effects, or fonts), but sometimes the modules are not very intuitive in terms of what use cases they solve (e.g., basic user interface or fragmentation). I therefore think it would be more useful for the guides to be in a separate place, but we should think carefully about the topics, and not just have them be the same as the modules. For example, we could organize them under Layout, Positioning, Filters and blending, Animations and transitions, CSS for language directions, or somesuchthing.

To be clear, I don't think this is a reason not to have CSS module pages, as some people will want to browse features by module. I just think they should be additional to the hierarchy.

Of course, this is just my opinion. I think we should do some more research to help make this decision. This doesn't have to hold up the whole reorganization. We could go ahead with the rest of the reorg, and leave the modules only versus modules and separate guides decision till later.

[dipikabh]

Thanks a lot, Chris, for taking the time to go through the proposal and sharing your thoughtful feedback. All excellent points.

We're now coming back to this reorganizing project after a pause, and I've also had the time to reflect on the structure and incorporate some great feedback from Ruth.

Essentially, in the latest proposal that I presented in the Editorial call today, there are two major changes from the previous version of the proposal. I'll capture them here for the record and for everyone's reference:

• Even though page-type remains the overall guiding factor for deciding where something belongs, say in one of reference/properties, reference/selectors, reference/values, reference/at-rules and so on, we're going to preserve the current directory structure even when a parent and child have different page-types.
  We have cases where function pages are child nodes of properties, data types, and at-rules; in these cases, we're going to keep this hierarchy intact, so the functions will stay with those parent directories instead of being moved into the "values" directory along with other functions.

  Some examples of such functions include:

  • animation-timeline > scroll() (files/en-us/web/css/animation-timeline/scroll/index.md)
  • <basic-shape> > ellipse() (files/en-us/web/css/basic-shape/ellipse/index.md)
  • @import > layer() (files/en-us/web/css/@import/layer_function/index.md)

  The idea is to keep related stuff together at the directory level. In terms of presentation on the website, properties and functions already appear separately in distinct buckets, but in the underlying directory structure, keeping them together makes it easier to see how they’re related and where they belong (also makes the breadcrumb the canonical truth of relationship).

  By extension, this also means that we'll keep modules and guides together the way they are now, which accurately depicts their relationship to each other.

• We're limiting the nesting within each major section (so e.g., stopping at css/reference/values/) and not creating additional sub-directories (for functions and types). This would also help with a manageable length of slug/URL and breadcrumbs.

  We'll rely on page titles to convey what a thing is. We'll tackle page titles separately after the moves are complete.
  So for example, after the move, the scroll() page will have the breadcrumb:
  Web > CSS > Reference > Properties > animation-timeline > scroll()
  And in a later phase, we'll update its page title to "scroll() function".

Feel free to check out the new proposed structure at https://github.com/dipikabh/mdn-css-reorg.

To answer your specific questions:

1. Yes, that's the intent, to have a landing or listing page for the top-level categories, one that's hopefully updated automatically via a macro. Maybe for a short time, we still might need to update them manually, but the goal is automatic generation of index.
2. For now, we'll just reuse the existing Tutorials page, which currently links to various guides in CSS and one Learn area guide. The idea is to build on it eventually.
3. We're keeping the modules and guides together, so the structure won't change from what it is now :). Only that all of the those directories will be moved under css/guides.

[chrisdavidmills]

Thanks for the updates, @dipikabh. I'm excited to see this work moving forward.

There isn't much that I disagree with here; a couple of further points:

• It still feels a little weird that the module landing pages are going to be underneath "guides" (am I understanding this right?). A separate "modules" directory would feel more logical. But I don't feel that strongly about it. It is still a much better structure than we currently have.
• "...we'll update its page title to "scroll() function"" -> would "scroll() CSS function" be better, to make it abundantly clear that these are not JS or API things? I know, under JS/APIs they are called methods...but even so? Additionally, it may be beneficial for SEO.

[dipikabh]

It still feels a little weird that the module landing pages are going to be underneath "guides" (am I understanding this right?).

That's correct.

A separate "modules" directory would feel more logical.

So the way the structure is right now is:
css / <module-landing-page-directory> / <one-or-more-guide-subdirectories>

We’ve essentially moved away from the idea of splitting "modules" and "guides" into separate folders.
Creating a separate "modules" directory would fragment this structure — that’s what I had tried in my previous proposal. I’ve since come around to keeping the related directories together, so the parent–child relationship between a module and related guides stays intact in the filesystem. I'll admit there are different ways to approach the IA; we're choosing the more functional route in this case.

For example, what we have now under /web/css:

├── css_custom_functions_and_mixins // module
│      └── using_custom_functions   // guide
├── css_custom_highlight_api        // module
├── css_display                    // module
│     ├── block_and_inline_layout_in_normal_flow      // guide
│     ├── block_formatting_context                   // guide

We're going to simply move this all as-is under /web/css/guides.

If we create a separate "modules" folder, we'd end up with:

css / guides
├── css_custom_functions_and_mixins
│      └── using_custom_functions
├── css_display
│     ├── block_and_inline_layout_in_normal_flow
│     ├── block_formatting_context 

AND

css / modules
├── css_custom_functions_and_mixins
├── css_custom_highlight_api
├── css_display

Another way to look at this is: if we create a separate "modules" directory, we’d see a lot of duplication of the same parent folders under both "modules" and "guides", and it would become difficult to tell from the directory which topics are missing from either. This was also a concern shared by Estelle.
For authors/contributors, it's best to keep the directory structure intuitive; that is, related directories in close proximity, as they are now.

On the site though, we already present "Modules" (since we don't have a listing page yet, see for example) and "Guides" as separate sections. Behind the scenes, we're choosing to group and keep the related pieces together.

I see this part of the move as just placing what we currently have—modules with their related guides—under the "css/guides" bucket without disturbing the structure any further. If in the future, we add guides that don’t belong to a module, we'd be able to add them directly under "css/guides". But I believe modules provide a nice framework of topics to cover, and so we should try and add guides corresponding to all modules where they're missing. (As an upshot, we can spot the missing guides more easily from the current structure.)

I imagine we'll still have to create a "css/guides/modules" directory during the move, but only as a home for a listing page that links out to all module pages.

Happy to hear if you had something completely different in mind.

would "scroll() CSS function" be better, to make it abundantly clear that these are not JS or API things?

Good point, that is definitely a possibility. We can look at all the options more closely when we get to the page title updates.

[chrisdavidmills]

Happy to hear if you had something completely different in mind.

Not vastly different, but I had a slightly different take on it. To be, it just seems weird that modules reference pages are inside guides/.

I'd be inclined to have the modules pages separate:

css / modules
├── css_custom_functions_and_mixins
├── css_custom_highlight_api
├── css_display

or maybe even

css / reference / modules
├── css_custom_functions_and_mixins
├── css_custom_highlight_api
├── css_display

The module pages could still link to the relevant guides in each case. It's just that I'd suggest putting them in a different place.

For the guides, I'd like to suggest that we have them in different category folders, but we make the category folders more intuitive than the modules. I'll give you a couple of examples:

• Some of the container queries guides are under the CSS containment module, and some are under the CSS conditional rules module. It would be much intuitive to have a single location for "Container queries guides".
• There's a bunch of different guides related to box model stuff, e.g. CSS box model, CSS box sizing. These would be better in one location.
• You can say similar things about guides under the different modules related to animation, handling overflow, colors, text, etc. The module pages are not very intuitive for finding all the information on a topic.

Instead, I'd suggest a guides directory arranged into more intuitive categories that don't necessarily have a 1:1 relationship with the modules, for example:

css / guides
├── animation
├── box_model
├── colors
├── container_queries
├── overflow
├── text
etc.
``

[dipikabh]

I see what you're saying and css / reference / modules was my original proposal.

But it's also not a bad idea to keep the grouping in the filesystem "by modules".
Under the current proposed structure with everything under css / guides, we can still add independent guides that do not have a 1:1 mapping with a module. We can also leverage the sidebar to surface more intuitive topic groupings (if they're missing) with existing guides.

For the examples you mention, we should perhaps update the Guides sections on the module pages to list and link to the relevant guides...like we do it in the Guides section of CSS box sizing module - here we link to guides under box sizing and box model.
Ah - just noticed that the only guide under css_box_sizing is Understanding and setting aspect ratios and that's missing a link in the sidebar which should definitely go under "Box model" in the sidebar.

In the container queries guide See also, we link to the "Using container scroll-state queries" that's under css_conditional_rules. But we can make a more prominent reference in prose as well if applicable.

You can say similar things about guides under the different modules related to animation, handling overflow, colors, text, etc. The module pages are not very intuitive for finding all the information on a topic.

Right. And we don't know if readers first navigate to the module pages and then the related guides. Probably folks go straight to Guides section in the sidebar and pick out the topic they're interested in. So we need to make our sidebar be reflective of the more searched for topics.
At least our new main CSS menu takes readers to "Guides". I wonder if readers really need the info about which module provides which feature. To me, it's a nice to know info and to understand how the specs are interconnected.

[chrisdavidmills]

The sidebar improvements definitely help. It'll be great to have an intuitive representation of different topic areas there.

I don't think this is a blocker. Your proposal is already much better than what we had before.

I'm still a bit concerned that some readers, at least, will find it weird and jarring to have these obvious reference pages under guides. But let's go forward and see how it pans out. We can always iterate further on it as feedback comes in.

[dipikabh]

Definitely 👍 Let's see how all the pieces fall after the move. We can always improve and fine tune. The key part like you said is feedback - we'll address if any concerns get flagged.

[dipikabh]

The CSS reorganization can be tracked in mdn/mdn#662.
There's a related discussion with updates about overall content organization on MDN: https://github.com/orgs/mdn/discussions/776.