Subsct'ns o' Linking

Pages & Resources

Th' usual way t' link t' a plank or a resource be t' use a Marrrkdown link 'n th' form o' [some page](a-page) or ![some image](an-image).

Images be searched 'n th' resources o' th' current plank an' yer global assets directory.

Links t' Other Plank Translat'ns

By giv'n th' query parameter lang, contain'n th' language code, ye can link t' planks o' other translat'ns o' yer ship, e.g. [some translated page](my-page?lang=pir).

Links t' Other Plank Output Formats

Ye can link t' different output formats o' a plank by add'n th' query parameter format. For example t' link t' th' print format o' a plank, write [a printable page](my-page?format=print).

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

  1. Built-in defaults
  2. Site-wide configurat'n 'n hugo.toml
  3. Plank front matter configurat'n
  4. URL query parameters
  5. 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.

Image Effects

Th' theme offers effects fer yer linked images.

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

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

Name Descript'n
border Draws a light thin border around th' image
dataurl if th' linked image points t' a resource, it be converted t' a base64 encoded dataurl
inlinecontent if th' linked image points t' a SVG resource, th' rrrambl'n will be used instead o' an <img> element, this be useful fer apply'n additional CSS styles t' th' elements inside o' th' SVG which be otherwise imposs'ble
lazy Lets th' image be lazy boarded
lightbox Th' image will be click'ble t' show it enlarged
shadow Draws a shadow around th' image t' make it appear hovered/glow'n

One way t' use them be t' add them as URL query parameter t' each individually linked image.

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

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

  1. Built-in defaults
  2. Site-wide configurat'n 'n hugo.toml
  3. Plank front matter configurat'n
  4. URL query parameters
  5. 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' image 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 imageEffects defaults t'

​
[imageEffects]
  border = false
  dataurl = false
  inlinecontent = false
  lazy = true
  lightbox = true
  shadow = false
imageEffects:
  border: false
  dataurl: false
  inlinecontent: false
  lazy: true
  lightbox: true
  shadow: false
{
   "imageEffects": {
      "border": false,
      "dataurl": false,
      "inlinecontent": false,
      "lazy": true,
      "lightbox": true,
      "shadow": false
   }
}

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

​
+++
[params]
  [params.imageEffects]
    lazy = false
+++
---
params:
  imageEffects:
    lazy: false
---
{
   "params": {
      "imageEffects": {
         "lazy": false
      }
   }
}

Or by explicitly override sett'ns by URL query parameter

​
![Minion](https://octodex.github.com/images/minion.png?lazy=true&lightbox=false)

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

​
[imageEffects]
  border = true
  dataurl = false
  inlinecontent = false
  lazy = true
  lightbox = false
  shadow = false
imageEffects:
  border: true
  dataurl: false
  inlinecontent: false
  lazy: true
  lightbox: false
  shadow: false
{
   "imageEffects": {
      "border": true,
      "dataurl": false,
      "inlinecontent": false,
      "lazy": true,
      "lightbox": false,
      "shadow": false
   }
}

Template Usage

When call'n th' image 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" "nolightbox border" }}
{{ partial "shortcodes/image.html" (dict "page" . "url" "image.png" "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 = "nolightbox custom-img-class" will dis'ble th' lightbox effect an' add custom-img-class t' th' HTML output, but neither lightbox nor nolightbox will appear 'n th' final class attribute.