twbs/bootstrap

Reusable Sass utilities API documentation section

Open

#38434 opened on Apr 10, 2023

View on GitHub
 (3 comments) (0 reactions) (0 assignees)MDX (174,240 stars) (78,904 forks)batch import
docsenhancementhelp wanted

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

Tech stack
htmlcssjavascript
Domain
documentationfrontend
Issue type
feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
stale
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
basic Hugo knowledge
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
70
Research direction
Review the discussion in PR #38219 for context on the requested shortcode. Examine existing Hugo shortcodes in the Bootstrap repository (e.g., `docsref` and `scss docs`) to understand syntax and integration. Implement a new shortcode named `sass utilities api section` that accepts two parameters and outputs the standardized boilerplate with calls to `scss docs` and `docsref`. Test by replacing a few existing documentation sections.