diff --git a/README.md b/README.md index 366c024ead..fb137e8128 100644 --- a/README.md +++ b/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) diff --git a/exampleSite/content/_index.en.md b/exampleSite/content/_index.en.md index 3f7c939b12..d2d4774c84 100644 --- a/exampleSite/content/_index.en.md +++ b/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) diff --git a/exampleSite/content/basics/migration/_index.en.md b/exampleSite/content/basics/migration/_index.en.md index 90761edebf..13aeecbc3e 100644 --- a/exampleSite/content/basics/migration/_index.en.md +++ b/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} diff --git a/exampleSite/content/shortcodes/attachments/index.en.md b/exampleSite/content/shortcodes/attachments/index.en.md index 40d9489c6f..7483cbcfa9 100644 --- a/exampleSite/content/shortcodes/attachments/index.en.md +++ b/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">}} diff --git a/exampleSite/content/shortcodes/attachments/index.pir.md b/exampleSite/content/shortcodes/attachments/index.pir.md index 9022bbbd2c..8c3d0249ba 100644 --- a/exampleSite/content/shortcodes/attachments/index.pir.md +++ b/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 >}} \ No newline at end of file diff --git a/exampleSite/content/shortcodes/resources/MaybeTreasure.en.txt b/exampleSite/content/shortcodes/resources/MaybeTreasure.en.txt new file mode 100644 index 0000000000..07fc7370ee --- /dev/null +++ b/exampleSite/content/shortcodes/resources/MaybeTreasure.en.txt @@ -0,0 +1 @@ +Nothing to see here :-( \ No newline at end of file diff --git a/exampleSite/content/shortcodes/resources/MaybeTreasure.pir.txt b/exampleSite/content/shortcodes/resources/MaybeTreasure.pir.txt new file mode 100644 index 0000000000..777f98ab13 --- /dev/null +++ b/exampleSite/content/shortcodes/resources/MaybeTreasure.pir.txt @@ -0,0 +1 @@ +Harrr, me found a trrreasure!!! \ No newline at end of file diff --git a/exampleSite/content/shortcodes/resources/NoTreasure.en.txt b/exampleSite/content/shortcodes/resources/NoTreasure.en.txt new file mode 100644 index 0000000000..07fc7370ee --- /dev/null +++ b/exampleSite/content/shortcodes/resources/NoTreasure.en.txt @@ -0,0 +1 @@ +Nothing to see here :-( \ No newline at end of file diff --git a/exampleSite/content/shortcodes/resources/Treasure.pir.txt b/exampleSite/content/shortcodes/resources/Treasure.pir.txt new file mode 100644 index 0000000000..777f98ab13 --- /dev/null +++ b/exampleSite/content/shortcodes/resources/Treasure.pir.txt @@ -0,0 +1 @@ +Harrr, me found a trrreasure!!! \ No newline at end of file diff --git a/exampleSite/content/shortcodes/resources/hugo.png b/exampleSite/content/shortcodes/resources/hugo.png new file mode 100644 index 0000000000..48acf346c9 Binary files /dev/null and b/exampleSite/content/shortcodes/resources/hugo.png differ diff --git a/exampleSite/content/shortcodes/resources/index.en.md b/exampleSite/content/shortcodes/resources/index.en.md new file mode 100644 index 0000000000..a5548f27c4 --- /dev/null +++ b/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.

- by severity: `info`, `note`, `tip`, `warning`
- by brand color: `primary`, `secondary`, `accent`
- by color: `blue`, `green`, `grey`, `orange`, `red`
- 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.

- for severity styles: a nice matching color for the severity
- 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.

- for severity styles: the matching title for the severity
- for all other styles: `Resources`

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.

- for severity styles: a nice matching icon for the severity
- for all other styles: `paperclip`

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:

- to match a file suffix of 'jpg', use `.*\.jpg` (not `*.\.jpg`)
- 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. diff --git a/exampleSite/content/shortcodes/resources/index.pir.md b/exampleSite/content/shortcodes/resources/index.pir.md new file mode 100644 index 0000000000..bf7ca78a0a --- /dev/null +++ b/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 >}} \ No newline at end of file diff --git a/layouts/partials/shortcodes/attachments.html b/layouts/partials/shortcodes/attachments.html index fe8e12526d..fac88b5f19 100644 --- a/layouts/partials/shortcodes/attachments.html +++ b/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" }} diff --git a/layouts/partials/shortcodes/resources.html b/layouts/partials/shortcodes/resources.html new file mode 100644 index 0000000000..8f80a00ca8 --- /dev/null +++ b/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 }} +
+
{{ if $icon }}{{ end }}{{ if and $icon $title }} {{ end }}{{ $title | .RenderString }}
+ + {{- $content }} +
+{{- end }} \ No newline at end of file diff --git a/layouts/shortcodes/resources.html b/layouts/shortcodes/resources.html new file mode 100644 index 0000000000..09f71ab518 --- /dev/null +++ b/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") +) }} \ No newline at end of file diff --git a/static/css/theme-neon.css b/static/css/theme-neon.css index 469c76daea..2ede784d8e 100644 --- a/static/css/theme-neon.css +++ b/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 */ diff --git a/static/css/theme.css b/static/css/theme.css index 77b32dfb77..2cc27147b6 100644 --- a/static/css/theme.css +++ b/static/css/theme.css @@ -667,7 +667,7 @@ p:empty { margin-bottom: 0; } -/* attachments shortcode */ +/* resources shortcode */ div.attachments .box-content { display: block;