Subsections of Linking

Pages & Resources

The usual way to link to a page or a resource is to use a Markdown link in the form of [some page](a-page) or ![some image](an-image).

Images are searched in the resources of the current page and your global assets directory.

Links to Other Page Translations

By giving the query parameter lang, containing the language code, you can link to pages of other translations of your site, e.g. [some translated page](my-page?lang=pir).

Links to Other Page Output Formats

You can link to different output formats of a page by adding the query parameter format. For example to link to the print format of a page, write [a printable page](my-page?format=print).

Link Effects

The theme offers effects for your linked links.

You can define additional custom link effects and set defaults in your configuration.

The default link effects shipped with the theme are

Name Description
download Causes the linked resource to be downloaded instead of shown in your browser.

- false: a usual link sending you to the location in your browser
- true: a link to download the resource
- <string>: a link to download the resource with the given filename
target Whether to show the link in a separate browser tab.

- false: shown in the same tab
- <string>: a valid a target value

If externalLinkTarget is configured and the URL is external, this will overwrite the link effect value of your hugo.toml and page’s front matter but can still be overwritten in the URL query parameter.

One way to use them is to add them as URL query parameter to each individual link.

This can become cumbersome to be done consistently for the whole site. Instead, you can configure the defaults in your hugo.toml as well as overriding these defaults in a page’s front matter.

Explicitly set URL query parameter will override the defaults set for a page or your site.

If an effect accepts boolean values, only setting the parameter name without a value in the URL will set it to true.

Without any settings in your hugo.toml linkEffects defaults to

​
[linkEffects]
  download = false
  target = false
linkEffects:
  download: false
  target: false
{
   "linkEffects": {
      "download": false,
      "target": false
   }
}

Front Matter This can be overridden in a pages front matter for example by

​
+++
[linkEffects]
  target = '_blank'
+++
---
linkEffects:
  target: _blank
---
{
   "linkEffects": {
      "target": "_blank"
   }
}

Or by explicitly override settings by URL query parameter

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

The settings applied to the above link would be

​
download = false
target = '_self'
download: false
target: _self
{
   "download": false,
   "target": "_self"
}

Image Effects

The theme offers effects for your linked images.

You can define additional custom image effects and set defaults in your configuration.

The default image effects shipped with the theme are

Name Description
border Draws a light thin border around the image
dataurl if the linked image points to a resource, it is converted to a base64 encoded dataurl
inlinecontent if the linked image points to a SVG resource, the content will be used instead of an <img> element, this is useful for applying additional CSS styles to the elements inside of the SVG which is otherwise impossible
lazy Lets the image be lazy loaded
lightbox The image will be clickable to show it enlarged
shadow Draws a shadow around the image to make it appear hovered/glowing

One way to use them is to add them as URL query parameter to each individually linked image.

This can become cumbersome to be done consistently for the whole site. Instead, you can configure the defaults in your hugo.toml as well as overriding these defaults in a page’s front matter.

Explicitly set URL query parameter will override the defaults set for a page or your site.

If an effect accepts boolean values, only setting the parameter name without a value in the URL will set it to true.

Without any settings in your hugo.toml imageEffects defaults to

​
[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 in a pages front matter for example by

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

Or by explicitly override settings by URL query parameter

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

The settings applied to the above image would be

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