Link Effects

Th' theme offers effects fer yer linked links.

Ye can define additional custom link effects an' set defaults 'n yer configurat'n.

Th' default link effects shipped wit' th' theme be

Name	Descript'n
download	Causes th' linked resource t' be downloaded instead o' shown 'n yer browser. - `false`: a usual link send'n ye t' th' locat'n 'n yer browser - `true`: a link t' download th' resource - <string>: a link t' download th' resource wit' th' given filename
target	Whether t' show th' link 'n a separate browser tab. - `false`: shown 'n th' same tab - <string>: a valid `a` `target` value If th' URL be external an' `externalLinkTarget` be set, it replaces th' value o' th' link effect configured on th' same level (eg. 'n yer `hugo.toml` or 'n th' page’s front matter). Nervertheless th' result'n value can still be overwritten by th' URL query parameter.

One way t' use them be t' add them as URL query parameter t' each individual link.

This can become cumbersome t' be done consistently fer th' whole ship. Instead, ye can configure th' defaults 'n yer hugo.toml as well as overrid'n these defaults 'n a page’s front matter.

Effect Priority

Link effects be applied 'n th' follow'n priority order (lowest t' highest):

Built-in defaults
Site-wide configurat'n 'n hugo.toml
Plank front matter configurat'n
URL query parameters
Template caller attributes parameter (highest priority)

Explicitly set URL query parameter will override th' defaults set fer a plank or yer ship. When call'n th' link partial directly from templates, effects passed via th' attributes parameter have th' highest priority an' will override all other sett'ns.

If an effect accepts boolean values, only sett'n th' parameter name without a value 'n th' URL will set it t' true.

Without any sett'ns 'n yer hugo.toml linkEffects defaults t'

[linkEffects]
  download = false
  target = false

linkEffects:
  download: false
  target: false

{
   "linkEffects": {
      "download": false,
      "target": false
   }
}

Front Matter This can be overridden 'n a planks front matter fer example by

+++
[params]
  [params.linkEffects]
    target = '_blank'
+++

---
params:
  linkEffects:
    target: _blank
---

{
   "params": {
      "linkEffects": {
         "target": "_blank"
      }
   }
}

Or by explicitly override sett'ns by URL query parameter

[Magic 'n new window](images/magic.gif?target=_self)

Th' sett'ns applied t' th' above link would be

[linkEffects]
  download = false
  target = '_self'

linkEffects:
  download: false
  target: _self

{
   "linkEffects": {
      "download": false,
      "target": "_self"
   }
}

Template Usage

When call'n th' link partial directly from templates, ye can pass effect preferences via th' attributes parameter. Effect names can be prefixed wit' no t' dis'ble them.

{{- $attributes := dict "class" "download" }}
{{ partial "shortcodes/link.html" (dict "page" . "url" "file.pdf" "content" "Download PDF" "attributes" $attributes) }}

This approach has th' highest priority an' will override all other effect sett'ns, includ'n URL query parameters. Effect classes be processed but not added t' th' final HTML class attribute. Non-effect classes pass through unchanged.

For example, class = "download custom-link-class" will en'ble th' download effect an' add custom-link-class t' th' HTML output, but download will not appear 'n th' final class attribute.