Reusable Sass utilities API documentation section

[julien-deramond]

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.

[guilhermejcgois]

@julien-deramond I came across this by chance and I was intrigued by how Hugo works with partial and shortcode and decided to try something. I arrived at this here:

<h3>Sass utilities API</h3>

{{ index .Params 0 }} utilities are declared in our utilities API in <code>scss/_utilities.scss</code>. <a href="{{ .Inner }}">Learn how to use the utilities API.</a>

And was testing with:

## CSS

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

{{< sass-utilities-api-section "Overflow" >}}
  {{< docsref "/utilities/api#using-the-api" >}}
{{< /sass-utilities-api-section >}}

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

However, I still ran into a problem with how the Inner variable is being populated with the result of the shortcode docsref, as there are spaces left at the beginning and end of the value.

Can give it one more try in the next weekend if the solutions sounds good and still desired. I'm not too familiar with Hugo, my closest contact is with other similar tools.

EDIT.: at this time, seems that Hugo doesn't support shortcode inside shortcode ;s

[julien-deramond]

Thanks @guilhermejcgois for digging this up 🙏

Can give it one more try in the next weekend if the solutions sounds good and still desired. I'm not too familiar with Hugo, my closest contact is with other similar tools.

Unfortunately, I can't check this out right now but if you find something as an improvement to the current situation that would be more maintainable, even if it's not exactly as described in the issue, you could create a draft PR and I'll jump on it to check this out with you.

I'm not too familiar with the advanced usage of Hugo either, but as you said in your edit, if I remember well Hugo doesn't support shortcode inside shortcode, which makes the task difficult.

[guilhermejcgois]

I came up with a possible solution, but at first I was worried about having something functional to discuss whether it made sense, etc. If you guys think it makes sense to continue with the (workaround) approach, then I will document it better and apply it to other pages as well.