Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: consistent usage of CSS sections #38219

Merged

Conversation

julien-deramond
Copy link
Member

@julien-deramond julien-deramond commented Mar 13, 2023

Description

Following #38175, this PR suggests more modifications in the way we display CSS and Sass info globally in our docs:

  • Most of the time, I've integrated when not already there a surrounding "CSS" section
  • I've systematically used the plural form for the section titles (even if they contained only 1 element):
    • "Sass mixin" → "Sass mixins"
    • "Sass loop" → "Sass loops"
    • "Sass map" → "Sass maps"
  • So it means that I also changed the URLs impacted by these modifications
  • In order to keep the same spirit of "Sass variables", "Sass mixins", "Sass loops":
    • "Utilities" → "Sass utilities API"
    • "Utilities API" → "Sass utilities API"

To summarize, here's the new structure:

## CSS
### Variables
### Sass variables
### Sass maps
### Sass mixins
### Sass loops
### Sass utilities API

Note
Regardingsite/content/docs/5.3/layout/css-grid.md, I decided to let it as is because the content is really linked to a limitation and doesn't seem to fit our regular CSS section.

Hope I haven't broken too much links in the process 😇

Motivation & Context

Docs headings global consistency around CSS and Sass.

Type of changes

  • Refactoring (non-breaking change)

Checklist

  • I have read the contributing guidelines
  • My code follows the code style of the project (using npm run lint)
  • My change introduces changes to the documentation
  • I have updated the documentation accordingly
  • (N/A) I have added tests to cover my changes
  • All new and existing tests passed

Live previews

Copy link
Member

@mdo mdo left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So far so good!

@julien-deramond julien-deramond force-pushed the main-jd-docs-consistent-usage-of-css-sections-step-2 branch from 7d9c614 to 6b62dab Compare March 17, 2023 13:10
@julien-deramond
Copy link
Member Author

julien-deramond commented Mar 17, 2023

@mdo I've updated this branch by going one step further in this refactoring for consistency. Love to hear your thoughts about it. Re-requesting a review (final this time).
Note: it can wait for the v5.3.0-beta

Copy link
Member

@mdo mdo left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Loving it, will give another review after alpha 2 ships, but this all looks great so far.

site/content/docs/5.3/forms/layout.md Outdated Show resolved Hide resolved

### Utilities API
### Sass utilities API

Overflow utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]({{< docsref "/utilities/api#using-the-api" >}})
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Realizing through this code review that, separately or here, we could perhaps turn this section (heading and paragraph) into an include with an argument lol. Maybe, maybe not.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The idea's great. We would need a shortcode or partial or anything else with two params:

  • First part of the sentence (e.g. "Background" or "Object fit")
  • The param (the key) used for scss-docs (e.g. "utils-bg-color")

The issue is I don't know how to build it with Hugo. I tried few things but haven't managed to succeed by calling scss-docs and docsref within another shortcode or form a partial.

Would like to call it like this:

{{< sass-utilities-api-section "Background" "utils-bg-color" >}}

And it would contain something like:

### Sass utilities API

{{ firstParam }} utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]({{< docsref "/utilities/api#using-the-api" >}})

{{< scss-docs name="{{ secondParam }}" file="scss/_utilities.scss" >}}

Maybe @XhmikosR you'd know how to do it

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mdo Maybe we can do it with a step-by-step approach: merge this PR, and create an issue to track this possible enhancement?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FYI tracked in #38434

@julien-deramond julien-deramond changed the title Docs: consistent usage of CSS sections in /helpers, /layout Docs: consistent usage of CSS sections Apr 10, 2023
@julien-deramond julien-deramond merged commit 01364cb into main Apr 10, 2023
@julien-deramond julien-deramond deleted the main-jd-docs-consistent-usage-of-css-sections-step-2 branch April 10, 2023 15:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
No open projects
Status: Done
Development

Successfully merging this pull request may close these issues.

2 participants