hugo-theme-relearn/exampleSite/content/shortcodes/attachments/index.en.md
2023-07-27 17:02:13 +02:00

5.2 KiB

+++ description = "List of files attached to a page" title = "Attachments" +++

The attachments shortcode displays a list of files attached to a page with adjustable color, title and icon.

{{% 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.

{{< tabs groupid="shortcode-parameter">}} {{% tab title="shortcode" %}}

{{%/* attachments sort="asc" /*/%}}

{{% /tab %}} {{% tab title="partial" %}}

{{ partial "shortcodes/attachments.html" (dict
  "page" .
  "sort" "asc"
)}}

{{% /tab %}} {{< /tabs >}}

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 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: Attachments

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]({{%relref "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 ascending or descending order.
pattern .* A regular expressions, used to filter the attachments by file 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)

Setup

Single language

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. If your page is a leaf bundle, attachments must be placed in a nested index.files folder, accordingly.

    • content
      • _index.md
      • page
        • _index.md
        • _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.

Eg. for a site in English and Piratish:

  • content
    • index.en.md
    • index.pir.md
    • page
      • index.en.md
      • index.pir.md
      • index.en.files
        • attachment.pdf
      • index.pir.files
        • attachment.pdf

Examples

Custom Title, List of Attachments Ending in pdf or mp4

{{%/* attachments title="Related **files**" pattern=".*\.(pdf|mp4)" /*/%}}

{{% attachments title="Related files" pattern=".*.(pdf|mp4)" /%}}

Info Styled Box, Descending Sort Order

{{%/* attachments style="info" sort="desc" /*/%}}

{{% attachments style="info" sort="desc" /%}}

With User-Defined Color and Font Awesome Brand Icon

{{%/* attachments color="fuchsia" icon="fab fa-hackerrank" /*/%}}

{{% attachments color="fuchsia" icon="fab fa-hackerrank" /%}}

Style, Color, Title and Icons

For further examples for style, color, title and icon, see the [notice shortcode]({{% relref "shortcodes/notice" %}}) documentation. The parameter are working the same way for both shortcodes, besides having different defaults.