Skip t' th' main rrreadin'

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 Versions

If yer ship be versioned, ye can link t' planks o' other versions by giv'n th' query parameter version, contain'n th' name o' th' version, e.g. [some archived page](my-page?version=v1.0.0).

Th' plank be searched 'n th' given version, so it has t' exist there under th' path ye link t'.

Ye can combine it wit' th' lang query parameter, e.g. [some archived translated page](my-page?lang=pir&version=v1.0.0).

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

By giv'n th' query parameter variant, contain'n th' identifier o' one o' yer configured color variants, th' linked plank be shown 'n that variant, e.g. [some dark page](my-page?variant=relearn-dark).

Th' variant stays selected fer th' follow'n presented planks, as if th' reader had selected it wit' th' variant switcher.

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 project configurat'n 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 project configurat'n 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 yer project configurat'n
  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 project configurat'n, 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:
  linkEffects:
    target: _blank
---
+++
[params]
  [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
rounded Rounds th' corners o' th' image
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 project configurat'n 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 yer project configurat'n
  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 project configurat'n, imageEffects defaults t'

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

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

​
---
params:
  imageEffects:
    lazy: false
---
+++
[params]
  [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
  rounded: true
  shadow: false
[imageEffects]
  border = true
  dataurl = false
  inlinecontent = false
  lazy = true
  lightbox = false
  rounded = true
  shadow = false
{
   "imageEffects": {
      "border": true,
      "dataurl": false,
      "inlinecontent": false,
      "lazy": true,
      "lightbox": false,
      "rounded": true,
      "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.