hugo-theme-relearn/exampleSite/content/shortcodes/attachments.en.md

109 lines
4 KiB
Markdown
Raw Normal View History

+++
description = "List of files attached to a page"
title = "Attachments"
+++
2017-08-20 15:10:29 +00:00
The `attachments` shortcode displays a list of files attached to a page with adjustable color, title and icon.
2017-08-20 15:10:29 +00:00
{{% attachments sort="asc" /%}}
2017-08-20 15:10:29 +00:00
## 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
{{%/* attachments sort="asc" /*/%}}
````
{{% /tab %}}
{{% tab name="partial" %}}
````go
{{ partial "shortcodes/attachments.html" (dict
"context" .
"sort" "asc"
)}}
````
{{% /tab %}}
{{< /tabs >}}
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`.
2017-08-20 15:10:29 +00:00
> * content
> * _index.md
> * **page.files**
2017-08-20 15:10:29 +00:00
> * 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:
2017-08-20 15:10:29 +00:00
> * content
> * _index.md
> * page
> * index.md
> * **index.files**
2017-08-20 15:10:29 +00:00
> * attachment.pdf
For leaf bundles:
> * content
> * _index.md
> * page
> * _index.md
> * **_index.files**
> * attachment.pdf
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:
2017-08-20 20:29:35 +00:00
> * content
> * _index.en.md
> * _index.pir.md
> * **page.en.files**
> * attachment.pdf
> * **page.pir.files**
> * attachment.pdf
> * page.en.md
> * page.pir.md
2017-08-20 15:10:29 +00:00
### Parameter
2017-08-20 15:10:29 +00:00
| Name | Default | Notes |
|:------------|:--------------|:------------|
2022-10-02 22:24:37 +00:00
| **style** | `transparent` | The color scheme used to highlight the box content.<br><br>- by severity: `info`, `note`, `tip`, `warning`<nd color: `primary`, `secondary`<br>- by color: `blue`, `green`, `grey`, `orange`, `red`<br>- by special color: `default`,t` |
2022-10-31 11:10:36 +00:00
| **title** | see notes | Arbitrary text for the box title. Depending on the **style** there may be a default title. Any given value will overwault.<br><br>- for severity styles: the matching title for the severity<br>- for all other colors: `Attachments`<br><br>If you wa you have to set this parameter to `" "` (a non empty string filled with spaces) |
2022-12-02 17:31:54 +00:00
| **icon** | see notes | [Font Awesome icon name]({{%relref "shortcodes/icon#finding-an-icon" %}}) set to the left of the title. Depending le** there may be a default icon. Any given value will overwrite the default.<br><br>- for severity styles: a nice matching iseverity<br>- for all other colors: `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. |
2022-10-02 22:24:37 +00:00
| **pattern** | `.*` | A [regular expressions](https://en.wikipedia.org/wiki/Regular_expression), used to filter the attachments by file 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)` |
2017-08-20 15:10:29 +00:00
## Examples
2017-08-20 15:10:29 +00:00
### Custom Title, List of Attachments Ending in pdf or mp4
2017-08-20 15:10:29 +00:00
````go
{{%/* attachments title="Related files" pattern=".*(pdf|mp4)" /*/%}}
````
2017-08-20 15:10:29 +00:00
{{% attachments title="Related files" pattern=".*(pdf|mp4)" /%}}
2017-08-20 15:10:29 +00:00
### Info Styled Box, Descending Sort Order
2017-08-20 15:10:29 +00:00
````go
{{%/* attachments style="info" sort="desc" /*/%}}
````
2017-08-20 15:10:29 +00:00
{{% attachments style="info" sort="desc" /%}}
2017-08-20 15:10:29 +00:00
### Style and Icons
2017-08-20 15:10:29 +00:00
For further examples for **style**, **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.