twbs/bootstrap

Reusable Sass utilities API documentation section

Open

#38,434 opened on Apr 10, 2023

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

Repository metrics

Stars
 (174,240 stars)
PR merge metrics
 (Avg merge 4d 15h) (99 merged PRs in 30d)

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

Research direction
Study Hugo's shortcode and partial documentation. Create a new shortcode that accepts two parameters and outputs the desired HTML. Ensure you can call `scss docs` and `docsref` from within the shortcode by using Hugo's `{{ partial }}` and `{{ .Get }}` functions. Test by adding it to a documentation page.
Tech stack
javascriptcsshtml
Domain
documentationfrontend
Issue type
Feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
Half day
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
GitHugo
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
65