docs: clarify limitations attachments shortcode in Hugo <0.112 #540

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

@@ -20,6 +20,12 @@ This document shows you what's new in the latest release. For a detailed list of
 
 ## 5.15.0 (2023-05-25)
 
+- {{% badge style="note" title=" " %}}Change{{% /badge %}} Now also compatible with Hugo {{% badge color="fuchsia" icon="fab fa-hackerrank" title=" " %}}0.112.0{{% /badge %}} or higher. This does not change the minimum required Hugo version.
+
+  The [`attachments` shortcode]({{% relref "shortcodes/attachments" %}}) has compatiblity issues with newer Hugo versions. You must switch to leaf bundles or are locked to Hugo < `0.112.0` for now.
+
+  It is [planned to refactor](https://github.com/McShelby/hugo-theme-relearn/issues/22) the `attchments` shortcode in the future. This will make it possible to use the shortcode in branch bundles again but not in simple pages anymore. Sadly this most likely will come with a breaking change which requires you to make changes to your project.
+
 - {{% 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.
@@ -28,8 +34,6 @@ This document shows you what's new in the latest release. For a detailed list of
 
   Additionally for such a use case, the whitespace between a tab outline and the code is removed if only a single code block is contained.
 
-- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Now also compatible with {{% badge color="fuchsia" icon="fab fa-hackerrank" title=" " %}}0.112.0{{% /badge %}} or higher. This does not change the minimum required Hugo version.
-
 - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Besides the _tag_ [taxonomy]({{% relref "cont/taxonomy" %}}) the theme now also provides the _category_ taxonomy out of the box and shows them in the content footer of each page.
 
 ---

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

@@ -7,6 +7,10 @@ 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`.
+{{% /notice %}}
+
 ## Usage
 
 While the examples are using shortcodes with named parameter you are free to also call this shortcode from your own partials.
@@ -48,26 +52,7 @@ While the examples are using shortcodes with named parameter you are free to als
 
 The shortcode lists files found in a specific folder. The name of the folder depends on your page type (either branch bundle, leaf bundle or page).
 
-1. For simple pages, attachments must be placed in a folder named like your page and ending with `.files`.
+1. If your page is a leaf bundle, attachments must be placed in a nested `index.files` folder, accordingly.
-
-    > * content
-    >   * _index.md
-    >   * **page.files**
-    >      * attachment.pdf
-    >   * page.md
-
-2. If your page is a branch or leaf bundle, attachments must be placed in a nested `_index.files` or `index.files` folder, accordingly.
-
-    For branch bundles:
-
-    > * content
-    >   * _index.md
-    >   * page
-    >      * index.md
-    >      * **index.files**
-    >          * attachment.pdf
-
-    For leaf bundles:
 
     > * content
     >   * _index.md
@@ -76,6 +61,27 @@ The shortcode lists files found in a specific folder. The name of the folder dep
     >     * **_index.files**
     >       * attachment.pdf
 
+2. If your page is a branch bundle, attachments must be placed in a nested `_index.files` folder, accordingly.
+
+    {{% badge style="warning" title=" " %}}Warning{{% /badge %}} This is only available for Hugo < `0.112.0`
+
+    > * content
+    >   * _index.md
+    >   * page
+    >     * index.md
+    >     * **index.files**
+    >       * attachment.pdf
+
+3. For simple pages, attachments must be placed in a folder named like your page and ending with `.files`.
+
+    {{% badge style="warning" title=" " %}}Warning{{% /badge %}} This is only available for Hugo < `0.112.0`
+
+    > * content
+    >   * _index.md
+    >   * **page.files**
+    >     * attachment.pdf
+    >   * page.md
+
 ### Multilingual
 
 Be aware that if you use a multilingual website, you will need to have as many folders as languages and the language code must be part of the folder name.
@@ -83,14 +89,15 @@ Be aware that if you use a multilingual website, you will need to have as many f
 Eg. for a site in English and Piratish:
 
   > * content
-  >   * _index.en.md
+  >   * index.en.md
-  >   * _index.pir.md
+  >   * index.pir.md
-  >   * **page.en.files**
+  >   * page
+  >     * index.en.md
+  >     * index.pir.md
+  >     * **index.en.files**
   >       * attachment.pdf
-  >   * **page.pir.files**
+  >     * **index.pir.files**
   >       * attachment.pdf
-  >   * page.en.md
-  >   * page.pir.md
 
 ## Examples