Adding shortcode for accordion component (Bootstrap 5)

assets/js/anchor.js

@@ -24,7 +24,7 @@ limitations under the License.
         if (!article) {
             return;
         }
-        var headings = article.querySelectorAll('h1, h2, h3, h4, h5, h6');
+        var headings = article.querySelectorAll('h1, h2:not(.accordion-header), h3, h4, h5, h6');
         headings.forEach(function (heading) {
             if (heading.id) {
                 var a = document.createElement('a');

assets/scss/shortcodes.scss

@@ -1,2 +1,3 @@
 @import "shortcodes/tabbed-pane.scss";
 @import "shortcodes/cards-pane.scss";
+@import "shortcodes/accordion.scss";

assets/scss/shortcodes/accordion.scss

@@ -0,0 +1,32 @@
+.accordion {
+  --bs-accordion-bg: #fff important;
+  max-width: 80%;
+}
+
+.accordion-button:not(.collapsed) {
+  background-color: #e7f1ff;
+}
+
+.accordion-button:focus {
+  box-shadow: none;
+}
+
+.accordion-collapse.show, .accordion-collapse.open
+{
+  --bs-accordion-border-width: 0px important;
+  border-left: 1px solid #dee2e6;
+  border-right: 1px solid #dee2e6;
+}
+
+.accordion-item {
+  --bs-accordion-border-width: 0px important;
+}
+
+.accordion-item:last-of-type {
+  border-bottom: 1px solid #dee2e6;
+}
+
+.accordion-button {
+  --bs-accordion-border-width: 1px important;
+  border: 1px solid #dee2e6;
+}

layouts/shortcodes/accordion-item.html

@@ -0,0 +1,32 @@
+{{- /* Make sure that we are enclosed within a accordion shortcode block */ -}}
+{{ with $.Parent -}}
+{{ if ne $.Parent.Name "accordion" -}}
+    {{ errorf "shortcode 'accordion-item' must be used within an 'accordion' block" -}}
+  {{ end -}}
+{{ end -}}
+
+{{ $header := "Header" -}}
+{{ if and (not .IsNamedParams) (.Get 0) -}}
+  {{ $header = (.Get 0) -}}
+{{ else -}}
+  {{/* Prefill header if not given as named or unnamed parameter */ -}}
+  {{ $header = default (printf "Header %v" ( add $.Ordinal 1)) (.Get "header") -}}
+{{ end -}}
+
+{{/* store all tab info in dict item */ -}}
+{{ $item := dict "header" $header -}}
+{{ with $.Get "open" -}}
+  {{ if ne ( printf "%T" . ) "bool" -}}
+  {{ errorf "shortcode 'accordion-item': parameter 'open' must be either true or false" -}}
+  {{ end -}}
+  {{ $item = merge $item (dict "open" ($.Get "open")) -}}
+{{ end -}}
+
+{{ with $.Inner -}}
+  {{ $item = merge $item (dict "content" $.Inner) -}}
+{{ end -}}
+
+{{/* add dict tab to parent's scratchpad */ -}}
+{{ with .Parent -}}
+  {{ $.Parent.Scratch.SetInMap "items" (printf "%02v" $.Ordinal) $item -}}
+{{ end -}}

layouts/shortcodes/accordion.html

@@ -0,0 +1,40 @@
+{{/* Check parameter type */ -}}
+{{ with .Get "alwaysOpen" -}}
+  {{ warnf "Always open given" }}
+  {{ $type := printf "%T" . -}}
+  {{ if ne $type "bool" -}}
+    {{ errorf `shortcode 'accordion': boolean value expected for parameter 'alwaysOpen', but got %s` $type -}}
+  {{ end -}}
+{{ end -}}
+
+{{ $alwaysOpen := default false ($.Get "alwaysOpen") -}}
+
+{{- /* Scratchpad gets populated through call to .Inner */ -}}
+{{- .Inner -}}
+
+{{/* Accordion markup */ -}}
+<div id="accordion-{{- $.Ordinal -}}" class="accordion mb-4">
+  {{ range $index, $element := $.Scratch.Get "items" -}}
+    {{ $itemid := printf "-%02v-%v" $.Ordinal $index | anchorize -}}
+
+    {{ $open := false -}}
+    {{ with $element.open -}}
+      {{ $open = . -}}
+    {{ end -}}
+
+    <div class="accordion-item">
+      <div class="accordion-header" id="heading{{- $itemid -}}">
+        <button class="accordion-button {{- cond ( eq $index "00" ) "" " collapsed" -}}" type="button" data-bs-toggle="collapse" data-bs-target="#collapse{{- $itemid -}}"
+                aria-controls="collapse{{- $itemid -}}" aria-expanded="{{- cond ( eq $index "00" ) "true" "false" -}}">
+        {{ index . "header" | markdownify }}
+        </button>
+      </div>
+      <div id="collapse{{- $itemid -}}" class="accordion-collapse {{ cond $open "open" "collapse" }} {{- cond ( eq $index "00" ) " show" ""  -}}" 
+           aria-labelledby="heading{{- $itemid -}}" {{ if not $alwaysOpen -}}data-bs-parent="#accordion-{{- $.Ordinal -}}"{{- end }}>
+        <div class="accordion-body">
+          {{ index . "content" }}
+        </div>
+      </div>
+    </div>
+  {{- end }}
+</div>

userguide/content/en/docs/adding-content/shortcodes/index.md

@@ -22,7 +22,7 @@ the shortcode body as Markdown. You can use both styles in your pages.
 
 ## Shortcode blocks
 
-The theme comes with a set of custom  **Page Block** shortcodes that can be used to compose landing pages, about pages, and similar.
+The theme comes with a set of custom **Page Block** shortcodes that can be used to compose landing pages, about pages, and similar.
 
 These blocks share some common parameters:
 
@@ -111,7 +111,7 @@ For announcement of latest features etc.
 {{</* /blocks/section */>}}
 ```
 
-| Parameter        | Default    | Description  |
+| Parameter        | Default    | Description |
 | ---------------- |------------| ------------|
 | `height` | | See above.
 | `color` | | See above.
@@ -125,7 +125,7 @@ We do a [Pull Request](https://github.com/gohugoio/hugo/pulls) contributions wor
 {{%/* /blocks/feature */%}}
 ```
 
-| Parameter        | Default    | Description  |
+| Parameter        | Default    | Description |
 | ---------------- |------------| ------------|
 | title | | The title to use.
 | url | | The URL to link to.
@@ -142,7 +142,7 @@ The **blocks/link-down** shortcode creates a navigation link down to the next se
 </div>
 ```
 
-| Parameter        | Default    | Description  |
+| Parameter        | Default    | Description |
 | ---------------- |------------| ------------|
 | color | info | See above.
 
@@ -706,4 +706,50 @@ This text does not appear in the output if `buildCondition = "bar" is set in you
 
 If you are using this shortcode, note that when evaluating the conditions, substring matches are matches as well. That means, if you set `include-if="foobar"`, and `buildcondition = "foo"`, you have a match!
 
+## Accordion
+
+Sometimes it's very useful to have an accordion element at hand when authoring content. One common use-case is FAQ section where only one section (= accordion item) will be open at any time. The following sample showcases a accordion presenting the four principles of object-oriented programming: 
+
+### Sample accordion: Object-oriented programming
+
+{{< accordion alwaysOpen=false >}}
+{{% accordion-item header="Principle 1:&nbsp;**Abstraction**" %}}
+**Abstraction** is the process of showing only essential/necessary features of an entity/object to the outside world and hide the other irrelevant information. For example to shut on/off your TV you only have a on/off method (≙ power button). It is not required to understand what internal processes are triggered in order to power on/off your TV device.
+{{% /accordion-item %}}
+{{% accordion-item header="Principle 2:&nbsp;**Encapsulation**" %}}
+**Encapsulation** means wrapping up data and member functions (methods) together into a single unit, commonly referred to as class. One aspect of encapsulation is the concept of data hiding. We can hide data by marking variables as private and expose only needed properties (getters and setters) to the public. Internally, these properties make use of the private data not exposed to the public.
+{{% /accordion-item %}}
+{{% accordion-item header="Principle 3:&nbsp;**Inheritance**" %}}
+**Inheritance** is the ability of creating a new class from an existing class. A child object acquires the property of a parent object. By means of inheritance, we achieve that a child class (subclass) acquires the properties and behavior of another parent class (super-class).
+{{% /accordion-item %}}
+{{% accordion-item header="Principle 4:&nbsp;**Polymorphism**" %}}
+**Polymorphism** is derived from two Greek words: _πολύς_ (`polús`) translates to `many` and _μορφή_ (`morphḗ`) to `form`. So polymorphism means `many forms`. A child/subclass can define its own unique behavior and still share the same functionalities or behavior of its parent/base class. A subclass can have their own behavior and share some of its behavior from its parent class not the other way around. A parent class cannot have the behavior of its subclass.
+{{% /accordion-item %}}
+{{% /accordion %}}
+
+The Docsy template provides two shortcodes `accordion` and `accordion-item` that let you easily create an accordion component. To see how to use them, have a look at the following code block, which renders to the accordion shown above:
+
+```go-html-template
+{{%/* accordion alwaysOpen=false */%}}
+{{%/* accordion-item header="Principle 1: Abstraction" */%}}
+**Abstraction** is the process of ...
+{{%/* /accordion-item */%}}
+{{%/* accordion-item header="Principle 2: Encapsulation" */%}}
+**Encapsulation** means wrapping up data ...
+{{%/* /accordion-item */%}}
+{{%/* accordion-item Principle 3: Inheritance */%}}
+**Inheritance** is the ability of creating a new class ...
+{{%/* /accordion-item */%}}
+... fourth item omitted
+{{%/* /accordion %}}
+```
+
+### Shortcode details
+
+An accordion component is implemented using two shortcodes:
+
+* The `accordion` shortcode, which is the container element for the collapsible items of the accordion. This shortcode can hold the optional named parameters `alwaysOpen`, and `flush`. Specify `alwaysOpen=true` if you want to make accordion items stay open even when another item is opened.
+
+* The various `accordion-item` shortcodes represent the collapsible items of your accordion. Specify the named parameter `header` for each `accordion-item` in order to set the header text of the item. If the `header` parameter is the only parameter inside your `accordion-item` shortcode, you can specify the header as unnamed parameter, something like `{{</* accordion-item "My header" */>}} … {{</* /accordion-item */>}}`. If your `accordion-item` shortcode does not have any parameters, the header of the item will default to `Header n`. When specifying `open=true` for an `accordion-item`, this item will be initially rendered opened (as opposed to an default collapsed item). If your item content is markdown, use the percent sign `%` as outermost delimiter of your `accordion-item` shortcode, your markup should look like `{{%/* accordion-item */%}}`Your \*\*markdown\*\* content`{{%/* /accordion-item */%}}`. In case of HTML content, use square brackets `<>` as outermost delimiters: `{{</* accordion-item */>}}`Your &lt;b&gt;HTML&lt;/b&gt; content`{{</* /accordion-item */>}}`.
+
 [shortcode delimiter]: https://gohugo.io/content-management/shortcodes/#use-shortcodes