resources: new shortcode to deprecate attachments shortcode #22

README.md

@@ -46,7 +46,7 @@ The Relearn theme is a fork of the great [Learn theme](https://github.com/matcor
   - [Image effects like sizing, shadow, border and alignment](https://mcshelby.github.io/hugo-theme-relearn/cont/markdown#image-effects)
   - [Image lightbox](https://mcshelby.github.io/hugo-theme-relearn/cont/markdown#lightbox)
 - **Shortcodes galore**
-  - [Display files attached to page bundles](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/attachments)
+  - [Display resources contained in a page bundle](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/resources)
   - [Marker badges](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/badge)
   - [Configurable buttons](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/button)
   - [List child pages](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/children)

exampleSite/content/_index.en.md

@@ -49,7 +49,7 @@ The theme is a fork of the great [Learn theme](https://github.com/matcornic/hugo
   - [Image effects like sizing, shadow, border and alignment](cont/markdown#image-effects)
   - [Image lightbox](cont/markdown#lightbox)
 - **Shortcodes galore**
-  - [Display files attached to page bundles](shortcodes/attachments)
+  - [Display resources contained in a page bundle](shortcodes/resources)
   - [Marker badges](shortcodes/badge)
   - [Configurable buttons](shortcodes/button)
   - [List child pages](shortcodes/children)

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

@@ -20,7 +20,13 @@ This document shows you what's new in the latest release and flags it with one o
 
 ## 5.25.0.beta (XXX) {#5250}
 
-- {{% badge style="note" title=" " %}}Change{{% /badge %}} If you run Hugo with [GitInfo](https://gohugo.io/methods/page/gitinfo/) configured, the default page footer now prints out name, email address and date of the last commit. If you want to turn this off you either have to run Hugo without GitInfo (which is the default) or overwrite the `content-footer.html' partial.
+- {{% badge style="note" title=" " %}}Change{{% /badge %}} This release deprecates the [`attachments` shortcode](shortcodes/attachments) in favor of the new the [`resources` shortcode](shortcodes/resources).
+
+  If you are using Hugo below {{% badge color="fuchsia" icon="fab fa-hackerrank" title=" " %}}0.123.0{{% /badge %}}, you don't need to change anything as the old shortcode still works (but may generate warnings).
+
+  Other users are strongly advised to migrate as the `attachments` shortcode will not receive support anymore. Migration instructions are listed on the [`attachments` shortcode page](shortcodes/attachments#migration).
+
+- {{% badge style="note" title=" " %}}Change{{% /badge %}} If you run Hugo with [GitInfo](https://gohugo.io/methods/page/gitinfo/) configured, the default page footer now prints out name, email address and date of the last commit. If you want to turn this off you either have to run Hugo without GitInfo (which is the default) or overwrite the `content-footer.html` partial.
 
 ## 5.24.0 (2024-02-28) {#5240}
 

exampleSite/content/shortcodes/attachments/index.en.md

@@ -1,5 +1,6 @@
 +++
 description = "List of files attached to a page"
+hidden = "true"
 title = "Attachments"
 +++
 
@@ -8,11 +9,29 @@ The `attachments` shortcode displays a list of files attached to a page with adj
 {{% attachments sort="asc" /%}}
 
 {{% notice warning %}}
-Since Hugo {{% badge color="fuchsia" icon="fab fa-hackerrank" title=" " %}}0.112.0{{% /badge %}} this only works for leaf bundles. Branch bundles and simple pages must be switched to leaf bundles or you are currently locked to a Hugo version < `0.112.0`.
+This shortcode is deprecated in favor of the new the [`resources` shortcode](shortcodes/resources). See [migration instructions](#migration) below.
 {{% /notice %}}
 
+## Migration
+
+While this shortcode will still be available for some time, it does not receive support anymore. Start to migrate early, as it will be removed with the next major update of the theme.
+
+The `resources` shortcode leverages Hugo's resource feature for page bundles. It has all the same parameter as the `attachments` shortcode but applies the `pattern` directly on a resources `Name` attribute.
+
+To migrate your pages apply the following steps:
+
+1. If a page is not already a [page bundle](https://gohugo.io/content-management/page-bundles/) convert it
+2. Move your files to a valid destination inside of your page bundle (depending if you have a branch or a leaf bundle)
+3. Change the calls from the `attachments` shortcode to the [`resources` shortcode](shortcodes/resources) and adjust the `pattern` parameter to the new directory layout and the resources [`Name` attribute](https://gohugo.io/methods/resource/name/).
+
+Multilanguage features are not supported directly by the shortcode anymore but rely on Hugo's handling for resource translations.
+
 ## Usage
 
+{{% notice warning %}}
+Since Hugo {{% badge color="fuchsia" icon="fab fa-hackerrank" title=" " %}}0.112.0{{% /badge %}} this only works for leaf bundles. Branch bundles and simple pages must be switched to leaf bundles or you are currently locked to a Hugo version < `0.112.0`.
+{{% /notice %}}
+
 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">}}

exampleSite/content/shortcodes/attachments/index.pir.md

@@ -1,7 +1,8 @@
 +++
 descrption = "Th' Attachments shorrrtcode displays a list o' files attached t' a plank"
+hidden = "true"
 title = "Attachments"
 +++
-{{% attachments /%}}
+{{% attachments sort="asc" /%}}
 
 {{< piratify >}}

exampleSite/content/shortcodes/resources/MaybeTreasure.en.txt

@@ -0,0 +1 @@
+Nothing to see here :-(

exampleSite/content/shortcodes/resources/MaybeTreasure.pir.txt

@@ -0,0 +1 @@
+Harrr, me found a trrreasure!!!

exampleSite/content/shortcodes/resources/NoTreasure.en.txt

@@ -0,0 +1 @@
+Nothing to see here :-(

exampleSite/content/shortcodes/resources/Treasure.pir.txt

@@ -0,0 +1 @@
+Harrr, me found a trrreasure!!!

exampleSite/content/shortcodes/resources/index.en.md

@@ -0,0 +1,78 @@
++++
+description = "List resources contained in a page bundle"
+title = "Resources"
+[[resources]]
+  name = 'MaybeTreasure.txt'
+  src = 'MaybeTreasure.en.txt'
++++
+
+The `resources` shortcode displays the [titles](https://gohugo.io/methods/resource/title/) of resources contained in a [page bundle](https://gohugo.io/content-management/page-bundles/).
+
+{{% resources sort="asc" /%}}
+
+## 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 title="shortcode" %}}
+
+````go
+{{%/* resources sort="asc" /*/%}}
+````
+
+{{% /tab %}}
+{{% tab title="partial" %}}
+
+````go
+{{ partial "shortcodes/resources.html" (dict
+  "page" .
+  "sort" "asc"
+)}}
+````
+
+{{% /tab %}}
+{{< /tabs >}}
+
+Multilanguage features are not supported directly by the shortcode but rely on Hugo's handling for resource translations applied when the theme iterates over all available resources.
+
+### Parameter
+
+| Name        | Default         | Notes       |
+|-------------|-----------------|-------------|
+| **style**   | `transparent`   | The style scheme used for the box.<br><br>- by severity: `info`, `note`, `tip`, `warning`<br>- by brand color: `primary`, `secondary`, `accent`<br>- by color: `blue`, `green`, `grey`, `orange`, `red`<br>- by special color: `default`, `transparent`, `code` |
+| **color**   | see notes       | The [CSS color value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) to be used. If not set, the chosen color depends on the **style**. Any given value will overwrite the default.<br><br>- for severity styles: a nice matching color for the severity<br>- for all other styles: the corresponding color |
+| **title**   | see notes       | Arbitrary text for the box title. Depending on the **style** there may be a default title. Any given value will overwrite the default.<br><br>- for severity styles: the matching title for the severity<br>- for all other styles: `Resources`<br><br>If you want no title for a severity style, you have to set this parameter to `" "` (a non empty string filled with spaces) |
+| **icon**    | see notes       | [Font Awesome icon name](shortcodes/icon#finding-an-icon) set to the left of the title. Depending on the **style** there may be a default icon. Any given value will overwrite the default.<br><br>- for severity styles: a nice matching icon for the severity<br>- for all other styles: `paperclip`<br><br>If you want no icon, you have to set this parameter to `" "` (a non empty d with spaces) |
+| **sort**    | `asc`           | Sorting the output in `asc`ending or `desc`ending order. |
+| **pattern** | `.*`            | A [regular expressions](https://en.wikipedia.org/wiki/Regular_expression), used to filter the resources [by name](https://gohugo.io/methods/resource/name/). For example:<br><br>- to match a file suffix of 'jpg', use `.*\.jpg` (not `*.\.jpg`)<br>- to match file names ending in `jpg` or `png`, use `.*\.(jpg\|png)` |
+
+## Examples
+
+### Custom Title, List of Resources Ending in png, jpg or gif
+
+````go
+{{%/* resources title="Related **files**" pattern=".*\.(png|jpg|gif)" /*/%}}
+````
+
+{{% resources title="Related **files**" pattern=".*\.(png|jpg|gif)" /%}}
+
+### Info Styled Box, Descending Sort Order
+
+````go
+{{%/* resources style="info" sort="desc" /*/%}}
+````
+
+{{% resources style="info" sort="desc" /%}}
+
+### With User-Defined Color and Font Awesome Brand Icon
+
+````go
+{{%/* resources color="fuchsia" icon="fab fa-hackerrank" /*/%}}
+````
+
+{{% resources color="fuchsia" icon="fab fa-hackerrank" /%}}
+
+### Style, Color, Title and Icons
+
+For further examples for **style**, **color**, **title** and **icon**, see the [`notice` shortcode](shortcodes/notice) documentation. The parameter are working the same way for both shortcodes, besides having different defaults.

exampleSite/content/shortcodes/resources/index.pir.md

@@ -0,0 +1,10 @@
++++
+descrption = "List Rrresources shorrrtcode contained in a plank bundle"
+title = "Resources"
+[[resources]]
+  name = 'MaybeTreasure.txt'
+  src = 'MaybeTreasure.pir.txt'
++++
+{{% resources /%}}
+
+{{< piratify >}}

layouts/partials/shortcodes/attachments.html

@@ -3,6 +3,7 @@
   {{- $page = .context }}
   {{- warnf "%q: DEPRECATED parameter 'context' for shortcode 'attachments' found, use 'page' instead; see https://mcshelby.github.io/hugo-theme-relearn/basics/migration#5180" $page.File.Filename }}
 {{- end }}
+{{ warnf "%q: DEPRECATED shortcode `attachments` found, use `resources` instead; see https://mcshelby.github.io/hugo-theme-relearn/shortcodes/attachments#migration" $page.File.Filename }}
 {{- $color := .color | default "" }}
 {{- $content := .content }}
 {{- $style := .style | default "default" }}

layouts/partials/shortcodes/resources.html

@@ -0,0 +1,60 @@
+{{- $page := .page }}
+{{- if and (not $page) .context }}
+  {{- $page = .context }}
+  {{- warnf "%q: DEPRECATED parameter 'context' for shortcode 'resources' found, use 'page' instead; see https://mcshelby.github.io/hugo-theme-relearn/basics/migration#5180" $page.File.Filename }}
+{{- end }}
+{{- $color := .color | default "" }}
+{{- $content := .content }}
+{{- $style := .style | default "default" }}
+{{- if and (not $color) (eq (len $color) 0) }}
+  {{- $style = .style | default "transparent" }}
+{{- end }}
+{{- $title := .title }}
+{{- if not $title }}
+  {{- if eq $style "info" }}{{ $title = $style | T }}{{ end }}
+  {{- if eq $style "warning" }}{{ $title = $style | T }}{{ end }}
+  {{- if eq $style "note" }}{{ $title = $style | T }}{{ end }}
+  {{- if eq $style "tip" }}{{ $title = $style | T }}{{ end }}
+{{- end }}
+{{- $title = trim ($title | default ("Attachments-label" | T)) " " }}
+{{- $icon := .icon | default "" }}
+{{- if and (not $icon) (eq (len $icon) 0) }}
+  {{- $icon = "paperclip" }}
+  {{- if eq $style "info" }}{{ $icon = default "info-circle" }}{{ end }}
+  {{- if eq $style "warning" }}{{ $icon = default "exclamation-triangle" }}{{ end }}
+  {{- if eq $style "note" }}{{ $icon = default "exclamation-circle" }}{{ end }}
+  {{- if eq $style "tip" }}{{ $icon = default "lightbulb" }}{{ end }}
+{{- end }}
+{{- $icon = trim $icon " " }}
+{{- if and $icon (not (findRE ".*?\\bfa-\\w.*?" $icon)) }}
+  {{- $icon = printf "fa-fw fas fa-%s" $icon }}
+{{- end }}
+{{- $sort := .sort | default "asc" }}
+{{- $pattern := .pattern | default "" }}
+{{- with $page }}
+{{- if eq .BundleType "" }}
+  {{- warnf "%q: UNSUPPORTED usage of 'resources' shortcode found, use a page bundle instead" $page.File.Filename }}
+{{- end }}
+<div class="box attachments cstyle {{ $style }}"{{ if $color }} style="--VARIABLE-BOX-color: {{ $color }};"{{ end }}>
+  <div class="box-label">{{ if $icon }}<i class="{{ $icon }}"></i>{{ end }}{{ if and $icon $title }} {{ end }}{{ $title | .RenderString }}</div>
+  <ul class="box-content attachments-files">
+{{- range sort .Resources "Name" $sort }}
+  {{- if findRE $pattern .Name }}
+    {{- $size := len .Content }}
+    {{- $unit := "Byte-symbol" }}
+    {{- if ge $size 1024 }}
+      {{- $size = div $size 1024 }}
+      {{- $unit = "Kilobyte-symbol" }}
+    {{- end }}
+    {{- if ge $size 1024 }}
+      {{- $size = div $size 1024 }}
+      {{- $unit = "Megabyte-symbol" }}
+    {{- end }}
+    {{- $unitsymbol := $unit | T }}
+    <li><a href="{{ .RelPermalink }}">{{.Name}}</a> ({{$size}} {{$unitsymbol}})</li>
+  {{- end }}
+{{- end }}
+  </ul>
+  {{- $content }}
+</div>
+{{- end }}

layouts/shortcodes/resources.html

@@ -0,0 +1,11 @@
+{{- $_hugo_config := `{ "version": 1 }` }}
+{{- partial "shortcodes/resources.html" (dict
+  "page"    .Page
+  "color"   (.Get "color")
+  "content" .Inner
+  "icon"    (.Get "icon")
+  "pattern" (.Get "pattern")
+  "style"   (.Get "style")
+  "sort"    (.Get "sort")
+  "title"   (.Get "title")
+) }}

static/css/theme-neon.css

@@ -51,7 +51,7 @@
     --BOX-BG-color: rgba( 8, 8, 8, 1 ); /* background color of colored boxes */
     --BOX-TEXT-color: initial; /* text color of colored box content */
 
-    /* optional base colors for colored boxes as in attachments, badges, buttons and notice shortcode */
+    /* optional base colors for colored boxes as in badges, buttons, notice, etc. shortcode */
     --BOX-BLUE-color: rgba( 48, 117, 229, 1 ); /* background color of blue boxes */
     --BOX-BLUE-TEXT-color: var( --BOX-BLUE-color ); /* text color of blue boxes */
     --BOX-GREEN-color: rgba( 42, 178, 24, 1 ); /* background color of green boxes */

static/css/theme.css

@@ -667,7 +667,7 @@ p:empty {
     margin-bottom: 0;
 }
 
-/* attachments shortcode */
+/* resources shortcode */
 
 div.attachments .box-content {
     display: block;