twbs / twbs/bootstrap

Reusable Sass utilities API documentation section

Open
#38,434 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

docs enhancement help wanted
Dominant language
MDX
Stars
175k
Forks
78.6k
Avg merge
7h 19m
Merged PRs (30d)
35

Description

Enhancement suggested in https://github.com/twbs/bootstrap/pull/38219#discussion_r1148250058.

Our "Sass utilities API" sections are always written the same way.

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")

We 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" >}}

We would need some help to do it. On my side, I don't exactly how to build it with Hugo. I tried a few things but haven't managed to succeed by calling scss-docs and docsref within another shortcode or from a partial.

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 the existing scss-docs and docsref shortcodes, along with the repeated Sass utilities API sections that use them. Use scss/_utilities.scss and the issue’s example parameters to define the reusable section’s inputs and confirm that the generated documentation still links to the utilities API. Done means the repeated sections use the new abstraction without changing their rendered content.

Written by the indexing model from the issue text.

Assessment

Tech stack
sass
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.