tab: new shortcode to display single tab #538

README.md

@@ -57,7 +57,7 @@ The Relearn theme is a fork of the great [Learn theme](https://github.com/matcor
   - [Colorful boxes](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/notice)
   - [OpenAPI specifications using Swagger UI](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/openapi)
   - [Reveal you site's configuration parameter](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/siteparam)
-  - [Tabbed panels](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/tabs)
+  - [Single tabbed panels](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/tab) and [multiple tabbed panels](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/tabs)
 
 ## Installation & Usage
 

exampleSite/content/_index.en.md

@@ -61,6 +61,7 @@ The theme is a fork of the great [Learn theme](https://github.com/matcornic/hugo
   - [OpenAPI specifications using Swagger UI]({{%relref "shortcodes/openapi" %}})
   - [Reveal you site's configuration parameter]({{%relref "shortcodes/siteparam" %}})
   - [Tabbed panels]({{%relref "shortcodes/tabs" %}})
+  - [Single tabbed panels]({{%relref "shortcodes/tab" %}}) and [multiple tabbed panels]({{%relref "shortcodes/tabs" %}})
 
 ## Support
 

exampleSite/content/basics/migration/_index.en.md

@@ -18,6 +18,16 @@ This document shows you what's new in the latest release. For a detailed list of
 
 ---
 
+## 5.15.0 (2023-05-23)
+
+- {{% badge style="note" title=" " %}}Change{{% /badge %}} The [`tabs` shortcode]({{% relref "shortcodes/tabs" %}}) has changed behavior if you haven't set the `groupid` parameter.
+
+  Formerly all tab views without a `groupid` were treated as so they belong to the same group. Now, each tab view is treated as it was given a unique id.
+
+- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The already known [`tabs` shortcode]({{% relref "shortcodes/tabs" %}}) has a new friend the [`tab` shortcode]({{% relref "shortcodes/tab" %}}) to make it easier to create a tab view in case you only need one single tab. Really handy if you want to flag your code examples with a language identifier.
+
+---
+
 ## 5.14.0 (2023-05-20)
 
 - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The taxonomy pages received some love in this release, making them better leverage available screen space and adding translation support for the taxonomy names.

exampleSite/content/shortcodes/tab.en.md

@@ -0,0 +1,76 @@
++++
+description = "Show content in a single tab"
+title = "Tab"
++++
+
+You can use a `tab` shortcode to display a single tab.
+
+This is especially useful if you want to flag your code example with an explicit language.
+
+{{% tab name="c" %}}
+
+```python
+printf("Hello World!");
+```
+
+{{% /tab %}}
+
+## Usage
+
+While the examples are using shortcodes with named parameter you are free to also call this shortcode from your own partials.
+
+{{< tabs groupid="shortcode-parameter">}}
+{{% tab name="shortcode" %}}
+
+````go
+{{%/* tab name="c" */%}}
+```c
+printf("Hello World!");
+```
+{{%/* /tab */%}}
+````
+
+{{% /tab %}}
+{{% tab name="partial" %}}
+
+````go
+{{ partial "shortcodes/tab.html" (dict
+  "context" .
+  "name" "c"
+  "content" ("```c\nprintf(\"Hello World!\")\n```" | markdownify)
+)}}
+````
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### Parameter
+
+| Name                  | Default              | Notes       |
+|:----------------------|:---------------------|:------------|
+| **name**              | _&lt;empty&gt;_      | Arbitrary text for the name of the tab. |
+| _**&lt;content&gt;**_ | _&lt;empty&gt;_      | Arbitrary text to be displayed in the tab. |
+
+## Examples
+
+### Code with collapsed margins
+
+{{% tab name="Code" %}}
+
+```python
+printf("Hello World!");
+```
+
+{{% /tab %}}
+
+### Mixed content
+
+{{% tab name="Mixed" %}}
+
+A tab can not only contain code but arbitrary text. In this case text and code will get a margin.
+
+```python
+printf("Hello World!");
+```
+
+{{% /tab %}}

exampleSite/content/shortcodes/tab.pir.md

@@ -0,0 +1,5 @@
++++
+descrption = "Show rrrambl'n 'n a single tab"
+title = "Tab"
++++
+{{< piratify >}}

exampleSite/content/shortcodes/tabs.en.md

@@ -3,11 +3,13 @@ description = "Show content in tabbed views"
 title = "Tabs"
 +++
 
-The `tabs` shortcode displays arbitrary content in unlimited number of tabs.
+The `tabs` shortcode displays arbitrary content in an unlimited number of tabs.
 
-This comes in handy eg. for providing code snippets for multiple languages or providing configuration in different formats.
+This comes in handy eg. for providing code snippets for multiple languages.
 
-{{< tabs groupid="tabs-example-language" >}}
+If you only want a single tab in your group, you can instead call the [`tab` shortcode]({{% relref "shortcodes/tab" %}}) standalone.
+
+{{< tabs >}}
 {{% tab name="python" %}}
 
 ```python
@@ -52,7 +54,7 @@ echo "Hello World!"
 ````go
 {{ partial "shortcodes/tabs.html" (dict
   "context" .
-  "tabs" (slice
+  "content" (slice
     (dict
       "name" "python"
       "content" ("```python\nprint(\"Hello World!\")\n```" | markdownify)
@@ -71,27 +73,25 @@ echo "Hello World!"
 ### Parameter
 
 | Name                  | Default              | Notes       |
-|:----------------------|:-----------------|:------------|
-| **groupid**           | `default`        | Arbitrary name of the group the tab view belongs to.<br><br>Tab views with the same **groupid** sychronize their selected tab. This sychronization applies to the whole site! |
+|:----------------------|:---------------------|:------------|
+| **groupid**           | _&lt;random&gt;_     | Arbitrary name of the group the tab view belongs to.<br><br>Tab views with the same **groupid** sychronize their selected tab. The tab selection is restored automatically based on the `groupid` for tab view. If the selected tab can not be found in a tab group the first tab is selected instead.<br><br>This sychronization applies to the whole site! |
 | _**&lt;content&gt;**_ | _&lt;empty&gt;_      | Arbitrary number of tabs defined with the `tab` sub-shortcode. |
 
-{{% notice note %}}
-When using tab views with different content sets, make sure to use a common `groupid` for equal sets of tabs but distinct `groupid` for different sets.
-
-The tab selection is restored automatically based on the `groupid` and if it cannot find a tab item because it came from the `'default'` group on a different page then the first tab is selected instead.
-{{% /notice %}}
-
 ## Examples
 
-### Distinct `groupid`
+### Behavior of the `groupid`
 
+See what happens to the tab views while you select different tabs.
+
+While pressing a tab of group A switches all tab views of group A in sync (if the tab is available), the tabs of group B are left untouched.
+
+{{< tabs >}}
+{{% tab name="Group A, Tab View 1" %}}
 ````go
-{{</* tabs groupid="config" */>}}
+{{</* tabs groupid="a" */>}}
 {{%/* tab name="json" */%}}
 ```json
-{
-  "Hello": "World"
-}
+{ "Hello": "World" }
 ```
 {{%/* /tab */%}}
 {{%/* tab name="XML" */%}}
@@ -106,13 +106,48 @@ Hello = World
 {{%/* /tab */%}}
 {{</* /tabs */>}}
 ````
+{{% /tab %}}
+{{% tab name="Group A, Tab View 2" %}}
+````go
+{{</* tabs groupid="a" */>}}
+{{%/* tab name="json" */%}}
+```json
+{ "Hello": "World" }
+```
+{{%/* /tab */%}}
+{{%/* tab name="XML" */%}}
+```xml
+<Hello>World</Hello>
+```
+{{%/* /tab */%}}
+{{</* /tabs */>}}
+````
+{{% /tab %}}
+{{% tab name="Group B" %}}
+````go
+{{</* tabs groupid="b" */>}}
+{{%/* tab name="json" */%}}
+```json
+{ "Hello": "World" }
+```
+{{%/* /tab */%}}
+{{%/* tab name="XML" */%}}
+```xml
+<Hello>World</Hello>
+```
+{{%/* /tab */%}}
+{{</* /tabs */>}}
+````
+{{% /tab %}}
+{{< /tabs >}}
 
-{{< tabs groupid="tabs-example-config" >}}
+
+#### Group A, Tab View 1
+
+{{< tabs groupid="tab-example-a" >}}
 {{% tab name="json" %}}
 ```json
-{
-  "Hello": "World"
-}
+{ "Hello": "World" }
 ```
 {{% /tab %}}
 {{% tab name="XML" %}}
@@ -127,33 +162,27 @@ Hello = World
 {{% /tab %}}
 {{< /tabs >}}
 
-### Non-Distinct `groupid`
+#### Group A, Tab View 2
 
-See what happens to this tab view if you select **properties** tab from the previous example.
-
-````go
-{{</* tabs groupid="config" */>}}
-{{%/* tab name="json" */%}}
+{{< tabs groupid="tab-example-a" >}}
+{{% tab name="json" %}}
 ```json
-{
-  "Hello": "World"
-}
+{ "Hello": "World" }
 ```
-{{%/* /tab */%}}
-{{%/* tab name="XML" */%}}
+{{% /tab %}}
+{{% tab name="XML" %}}
 ```xml
 <Hello>World</Hello>
 ```
-{{%/* /tab */%}}
-{{</* /tabs */>}}
-````
+{{% /tab %}}
+{{< /tabs >}}
 
-{{< tabs groupid="tabs-example-config" >}}
+#### Group B
+
+{{< tabs groupid="tab-example-b" >}}
 {{% tab name="json" %}}
 ```json
-{
-  "Hello": "World"
-}
+{ "Hello": "World" }
 ```
 {{% /tab %}}
 {{% tab name="XML" %}}

layouts/partials/shortcodes/tab.html

@@ -0,0 +1,5 @@
+{{- partial "shortcodes/tabs.html" (dict
+    "context" .context
+    "groupid" ""
+    "content" (slice | append (dict "name" (trim .name " ") "content" .content))
+) }}

layouts/partials/shortcodes/tabs.html

@@ -1,5 +1,5 @@
 {{- $context := .context }}
-{{- $tabs := .tabs | default slice }}
+{{- $tabs := .content | default slice }}
 {{- $groupid := .groupid | default (partial "make-random-md5.hugo" $context) }}
 {{- with $context }}
 <div class="tab-panel" data-tab-group="{{ $groupid }}">
@@ -19,8 +19,7 @@
       data-tab-item="{{ .name }}"
       class="tab-content-text{{ cond (eq $idx 0) " active" ""}}"
     >
-{{ .content | safeHTML }}
-    </div>
+{{ .content | safeHTML }}</div><!-- no line break allowed here because of awkward behavior of Hugo 110 or this theme when tag shortcode is called standalone outside of tags shortcode ? -->
     {{- end }}
   </div>
 </div>

layouts/shortcodes/tab.html

@@ -1,10 +1,17 @@
 {{- $content := .Inner }}
 {{- $name := (.Get "name") }}
+{{- $tabs := slice }}
+{{- if and .Parent (.Parent.Scratch.Get "tabs") }}
+    {{- $tabs = .Parent.Scratch.Get "tabs" }}
+{{- end }}
+{{- $tabs = $tabs | append (dict "name" (trim $name " ") "content" $content) }}
 {{- if .Parent }}
-    {{- if not (.Parent.Scratch.Get "tabs") }}
-        {{- .Parent.Scratch.Set "tabs" slice }}
-    {{- end }}
-    {{- $.Parent.Scratch.Add "tabs" (dict "name" (trim $name " ") "content" $content ) }}
+    {{- $.Parent.Scratch.Set "tabs" $tabs }}
 {{- else }}
-    {{- errorf "[%s] %q: tab shortcode missing its parent" site.Language.Lang .Page.Path -}}
+    {{- $c:=""}}{{/* if no containing tabs shortcode is present, we display this tab as single */}}
+    {{- partial "shortcodes/tabs.html" (dict
+        "context" .Page
+        "groupid" ""
+        "content" $tabs
+    ) }}
 {{- end }}

layouts/shortcodes/tabs.html

@@ -1,6 +1,6 @@
+{{- $unused := .Inner }}
 {{- partial "shortcodes/tabs.html" (dict
   "context" .Page
-  "content" .Inner
   "groupid" ((.Get "groupid") | default (.Get "groupId"))
-  "tabs"    (.Scratch.Get "tabs")
+  "content" (.Scratch.Get "tabs")
 ) }}

static/css/tabs.css

@@ -31,6 +31,9 @@ html[dir="rtl"] #body .tab-nav-button{
 #body .tab-nav-button:first-child{
     margin-inline-start: 9px;
 }
+#body .tab-nav-button.active{
+    cursor: default;
+}
 #body .tab-nav-button:not(.active){
     border-bottom-color: rgba( 134, 134, 134, .1 );
     margin-top: 8px;
@@ -49,13 +52,20 @@ html[dir="rtl"] #body .tab-nav-button{
 	-webkit-print-color-adjust: exact;
 	color-adjust: exact;
     display: block;
-    padding: 8px;
     z-index: 10;
 }
 #body .tab-content-text{
     display: none;
+    margin: 8px;
+}
+/* remove margin if only a single code block is contained in the tab */
+#body .tab-content-text:has(> div.highlight:only-child){
+    margin: 0;
+}
+/* remove border from a code block if single  */
+#body .tab-content-text > div.highlight:only-child > pre{
+    border: 0;
 }
-
 #body .tab-content-text.active{
     display: block;
 }

theme.toml

@@ -21,7 +21,7 @@ features = ["badges", "breadcrumbs", "boxes", "buttons",
   "responsive", "rss", "rtl",
   "sidebar", "sitemap",
   "search", "search page", "subtheme", "swagger", "swaggerui", "syntax highlighting",
-  "table of contents", "tabs", "tags", "themeable", "themes", "toc"]
+  "table of contents", "tab", "tabs", "tags", "themeable", "themes", "toc"]
 
 [module]
   [module.hugoVersion]