Subsections of Authoring

Directory Structure

In Hugo, pages are the core of your site.

The theme generates the navigation menu out of the given directory structure.

Organize your site like any other Hugo project. Typically, you will have a content directory with all your pages.

  • content
    • log
      • first-day
        • _index.md
        • first-sub-page
          • _index.md
          • picture1.png
          • plain.txt
      • second-day
        • index.md
        • picture1.png
        • picture2.png
      • third-day.md
      • _index.md
    • _index.md
Note

While you can also go different, _index.md (with an underscore) is recommended for each directory, it’s your directory’s home page.

See Hugo’s guide for content to learn more.

Front Matter

Page Designs

How to vary layouts by using page designs

Menus

Setting the behavior of the menus

Linking

What options are available for links and images

Topbar

Configure the topbar

Reference

All front matter for the Relearn theme

Subsections of Front Matter

Page Designs

Page designs are used to provide different layouts for your pages.

A page is displayed by exactly one page design and is represented by Hugo’s reserved type front matter.

The Relearn theme ships with the page designs home, chapter, and default for the HTML output format but you can define further custom page designs.

Using a Page Design

Regardless of shipped or custom page design, you are using them in the same way.

  • If you have an archetype file, you can just do

    hugo new --kind chapter log/_index.md

  • If you are creating your Markdown files manually, you can achieve the same by just setting type='chapter' in the front matter to make your page displayed with the chapter page design.

    ​
    +++
title = "Captain's Log"
type = "chapter"
+++

If no type is set in your front matter or the page design doesn’t exist for a given output format, the page is treated as if type='default' was set.

Predefined Designs for the HTML Output Format

Home

A Home page is the starting page of your project. It’s best to have only one page of this kind in your project.

To create a home page, run the following command

hugo new --kind home _index.md

Home page Home page

Chapter

A Chapter displays a page meant to be used as introduction for a set of child pages.

Commonly, it contains a title front matter and a short description in the content.

To create a chapter page, run the following command

hugo new --kind chapter log/_index.md

If a numerical weight front matter is set, it will be used to generate the subtitle of the chapter page. Set the number to a consecutive value starting at 1 for each new chapter on the same directory level.

Chapter page Chapter page

Default

A Default page is any other content page.

To create a default page, run either one of the following commands

hugo new log/first-day/_index.md

or

hugo new log/second-day/index.md

or

hugo new log/third-day.md

Default page Default page

Menus

Linking

Option Front Matter By default, external links open in the same browser tab. To change this, use the externalLinkTarget setting with a proper link target.

To set default values for all links, use link effects.

For example, this will open all external links in a new tab

​
[params]
  externalLinkTarget = '_blank'
params:
  externalLinkTarget: _blank
{
   "params": {
      "externalLinkTarget": "_blank"
   }
}

Option Front Matter You can use link.errorlevel and image.errorlevel to control what should happen if a local link can not be resolved to a page and/or a resource.

If not set or empty, any unresolved link is written as given into the resulting output. If set to warning the same happens and an additional warning is printed in the built console. If set to error an error message is printed and the build is aborted.

Please note that this can not resolve files inside of your static directory. The file must be a resource of the page or the site.

Link warnings are also available for the include and openapi shortcodes.

​
[params]
  [params.image]
    errorlevel = 'warning'

  [params.link]
    errorlevel = 'warning'
params:
  image:
    errorlevel: warning
  link:
    errorlevel: warning
{
   "params": {
      "image": {
         "errorlevel": "warning"
      },
      "link": {
         "errorlevel": "warning"
      }
   }
}

Ignoring False Negatives

Option Front Matter In case you want to use link warnings but are bothered by false negatives, you can configure an ignore list of regular expressions. The referenced address will be checked against all regexes of this list. If the address matches at least one regex, no output will be written to the console. The check uses Hugo’s findRE function.

​
[params]
  urlIgnoreCheck = ['^/authoring/', '^/configuration/']
params:
  urlIgnoreCheck:
  - ^/authoring/
  - ^/configuration/
{
   "params": {
      "urlIgnoreCheck": [
         "^/authoring/",
         "^/configuration/"
      ]
   }
}

Check External URLs

Option Front Matter External URLs can be checked for validity during build. It will only be checked if the URL does not match a urlIgnoreCheck pattern.

​
[params]
  urlExternalCheck = true
params:
  urlExternalCheck: true
{
   "params": {
      "urlExternalCheck": true
   }
}

Topbar

This page is about how to configure the topbar using configuration options. If you want to add further buttons or functionality, see this section.

Your topbar contains the following elements. Some of them are configuarable:

Table of Contents

Option Front Matter Set disableToc=true to hide the TOC button on all pages. If the button is hidden, also the keyboard shortcut is disabled. This can be overridden in a page’s front matter.

​
disableToc = true
disableToc: true
{
   "disableToc": true
}

Option Front Matter Set disableBreadcrumb=true to hide the breadcrumb in the topbar.

Further breadcrumbs settings can be found in the content configuration section.

​
disableBreadcrumb = true
disableBreadcrumb: true
{
   "disableBreadcrumb": true
}

Edit Button

Option Front Matter If editURL is set to a URL, an edit button will be shown in the topbar. If the button is hidden, also the keyboard shortcut is disabled.

The value can contain the macro ${FilePath} which will be replaced by the file path of your displayed page. If no ${FilePath} is given in the value, the value is treated as if the ${FilePath} was appended at the end of the value. This can be overridden in the pages front matter.

​
editURL = 'https://github.com/McShelby/hugo-theme-relearn/edit/main/docs/content/${FilePath}'
editURL: https://github.com/McShelby/hugo-theme-relearn/edit/main/docs/content/${FilePath}
{
   "editURL": "https://github.com/McShelby/hugo-theme-relearn/edit/main/docs/content/${FilePath}"
}

Markdown Button

Option Front Matter You can hide the Markdown button if the Markdown output format is active by setting disableMarkdownButton=true.

​
disableMarkdownButton = true
disableMarkdownButton: true
{
   "disableMarkdownButton": true
}

Source Button

Option Front Matter You can hide the Source button if the Source output format is active by setting disableSourceButton=true.

​
disableSourceButton = true
disableSourceButton: true
{
   "disableSourceButton": true
}

Option Front Matter You can hide the print button if the print output format is active by setting disablePrintButton=true.

​
disablePrintButton = true
disablePrintButton: true
{
   "disablePrintButton": true
}

Arrow Navigation

Option Front Matter You can hide the previous/next buttons by setting disableNextPrev=true. If the buttons are hidden, also the keyboard shortcuts are disabled.

​
disableNextPrev = true
disableNextPrev: true
{
   "disableNextPrev": true
}

Front Matter Reference

Every Hugo page must have front matter.

In addition to Hugo’s standard front matter, the Relearn theme offers extras settings listed here.

Throughout the documentation, theme-specific front matter is marked with a Front Matter badge.

Add theme front matter directly to the root of your page’s front matter. For example:

​
+++
[params]
  math = true
+++
---
params:
  math: true
---
{
   "params": {
      "math": true
   }
}

Index

A

C

D

E

H

I

L

M

O

S

U

All Front Matter

Here’s a list of all available front matter with example values. Default values are described in the annotated example below or in each front matter’s documentation.

​
+++
[params]
  LastModifierDisplayName = ''
  LastModifierEmail = ''
  alwaysopen = ''
  collapsibleMenu = true
  customMathJaxURL = ''
  customMermaidURL = ''
  customOpenapiURL = ''
  disableBreadcrumb = false
  disableMarkdownButton = false
  disableNextPrev = false
  disablePrintButton = false
  disableSourceButton = false
  disableToc = false
  editURL = ''
  externalLinkTarget = '_self'
  headingPost = ''
  headingPre = ''
  hidden = false
  highlightWrap = true
  linkTitle = ''
  mathJaxInitialize = '{}'
  menuPageRef = ''
  menuPost = ''
  menuPre = ''
  menuUrl = ''
  mermaidInitialize = '{ "securityLevel": "loose" }'
  mermaidZoom = true
  ordersectionsby = 'weight'
  sidebarfootermenus = ''
  sidebarheadermenus = ''
  sidebarmenus = ''
  urlExternalCheck = false
  urlIgnoreCheck = []

  [params.image]
    errorlevel = ''

  [params.imageEffects]
    border = true
    dataurl = false
    inlinecontent = false
    lazy = true
    lightbox = true
    shadow = false

  [params.include]
    errorlevel = ''

  [params.link]
    errorlevel = ''

  [params.linkEffects]
    download = false
    target = false

  [params.math]
    force = false

  [params.mermaid]
    force = false

  [params.openapi]
    errorlevel = ''
    force = false
+++
---
params:
  LastModifierDisplayName: ''
  LastModifierEmail: ''
  alwaysopen: ''
  collapsibleMenu: true
  customMathJaxURL: ''
  customMermaidURL: ''
  customOpenapiURL: ''
  disableBreadcrumb: false
  disableMarkdownButton: false
  disableNextPrev: false
  disablePrintButton: false
  disableSourceButton: false
  disableToc: false
  editURL: ''
  externalLinkTarget: _self
  headingPost: ''
  headingPre: ''
  hidden: false
  highlightWrap: true
  image:
    errorlevel: ''
  imageEffects:
    border: true
    dataurl: false
    inlinecontent: false
    lazy: true
    lightbox: true
    shadow: false
  include:
    errorlevel: ''
  link:
    errorlevel: ''
  linkEffects:
    download: false
    target: false
  linkTitle: ''
  math:
    force: false
  mathJaxInitialize: '{}'
  menuPageRef: ''
  menuPost: ''
  menuPre: ''
  menuUrl: ''
  mermaid:
    force: false
  mermaidInitialize: '{ "securityLevel": "loose" }'
  mermaidZoom: true
  openapi:
    errorlevel: ''
    force: false
  ordersectionsby: weight
  sidebarfootermenus: ''
  sidebarheadermenus: ''
  sidebarmenus: ''
  urlExternalCheck: false
  urlIgnoreCheck: []
---
{
   "params": {
      "LastModifierDisplayName": "",
      "LastModifierEmail": "",
      "alwaysopen": "",
      "collapsibleMenu": true,
      "customMathJaxURL": "",
      "customMermaidURL": "",
      "customOpenapiURL": "",
      "disableBreadcrumb": false,
      "disableMarkdownButton": false,
      "disableNextPrev": false,
      "disablePrintButton": false,
      "disableSourceButton": false,
      "disableToc": false,
      "editURL": "",
      "externalLinkTarget": "_self",
      "headingPost": "",
      "headingPre": "",
      "hidden": false,
      "highlightWrap": true,
      "image": {
         "errorlevel": ""
      },
      "imageEffects": {
         "border": true,
         "dataurl": false,
         "inlinecontent": false,
         "lazy": true,
         "lightbox": true,
         "shadow": false
      },
      "include": {
         "errorlevel": ""
      },
      "link": {
         "errorlevel": ""
      },
      "linkEffects": {
         "download": false,
         "target": false
      },
      "linkTitle": "",
      "math": {
         "force": false
      },
      "mathJaxInitialize": "{}",
      "menuPageRef": "",
      "menuPost": "",
      "menuPre": "",
      "menuUrl": "",
      "mermaid": {
         "force": false
      },
      "mermaidInitialize": "{ \"securityLevel\": \"loose\" }",
      "mermaidZoom": true,
      "openapi": {
         "errorlevel": "",
         "force": false
      },
      "ordersectionsby": "weight",
      "sidebarfootermenus": "",
      "sidebarheadermenus": "",
      "sidebarmenus": "",
      "urlExternalCheck": false,
      "urlIgnoreCheck": []
   }
}

Annotated Front Matter

​
+++
[params]
# If an option value is said to be not set, you can achieve the same behavior
# by giving it an empty string value.

###############################################################################
# Hugo
# These options usually apply to other themes as well.

# The social media image of your page.
# Default: not set
# This is used for generating social media meta information for the opengraph
# protocol and twitter cards.
# If not set, the set value of your site's hugo.toml is used.
# images = [ 'images/hero.png' ]

# The title of your page.
# Default: not set
# A page without a title is treated as a hidden page.
# title = 'Example Page'

# The description of your page.
# Default: not set
# This is used for generating HTML meta tags, social media meta information
# for the opengraph protocol and twitter cards.
# If not set, the set value of your site's hugo.toml is used for the html
# meta tag, social media meta information for the opengraph protocol and
# twitter cards.
# description = ''

# The page design to be used
# Default: not set
# This decides the layout of your page. The theme ships 'home', 'chapter' and
# 'default'. If not set, 'default' is taken.
# type = ''

###############################################################################
# Relearn Theme
# These options are specific to the Relearn theme.

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# General
# These options are defining general, non visual behavior.

# Conditionally ignore errorlevel settings
# Default: []
# The theme supports checking referenced address (e.g. with
# link.errorlevel, image.errorlevel, etc. see below). Sometimes checks lead
# to console output due to false negatives. You can turn off the checks
# for individual referenced addresses by defining regular expressions here.
# The referenced address will be checked against all regexes of this array.
# If it matches at least one, no output will be written to the console.
# This array can be expanded globally in your site's hugo.toml.
urlIgnoreCheck = []

# Check external URLs
# Default: false
# If `true` the theme checks during build if an external URL is reachable.
# If it fails, it write errors according to the errorlevel settings. A check
# is omitted if the URL is found in the `urlIgnoreCheck` list.
# If not set, the set value of your site's hugo.toml is used.
urlExternalCheck = false

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Topbar
# These options modify the topbar appearance.

# Hide the table of contents button.
# Default: false
# If the TOC button is hidden, also the keyboard shortcut is disabled.
# If not set, the set value of your site's hugo.toml is used.
disableToc = false

# Hide the breadcrumbs.
# Default: false
# If the breadcrumbs are hidden, the title of the displayed page will still be
# shown in the topbar.
disableBreadcrumb = false

# Hide the Markdown button.
# Default: false
# This hides the Markdown button if you activated the Markdown output format.
# If not set, the set value of your site's hugo.toml is used.
disableMarkdownButton = false

# Hide the Source button.
# Default: false
# This hides the Source button if you activated the Source output format.
# If not set, the set value of your site's hugo.toml is used.
disableSourceButton = false

# Hide the Print button.
# Default: false
# This hides the print button if you activated the print output format.
# If not set, the set value of your site's hugo.toml is used.
disablePrintButton = false

# Hide Next and Previous navigation buttons.
# Default: false
# If the navigation buttons are hidden, also the keyboard shortcuts are
# disabled.
disableNextPrev = false

# The URL prefix to edit a page.
# Default: not set
# If set, an edit button will be shown in the topbar. If the button is hidden,
# also the keyboard shortcuts are disabled. The value can contain the macro
# `${FilePath}` which will be replaced by the file path of your displayed page.
# If not set, the set value of your site's hugo.toml is used. If the global
# parameter is given but you want to hide the button for the displayed page,
# you can set the value to an empty string. If instead of hiding you want to have
# an disabled button, you can set the value to a string containing just spaces.
# This is useful if you want to give the opportunity for people to create merge
# request for your content.
editURL = ''

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Menu
# These options modify the menu appearance.

# Menu specific title
# Default: not set
# The title displayed in the menu. If not set the `title` front matter will
# be used.
linkTitle = ''

# Prefix for the title in navigation menu.
# Default: not set
# The title of the page in the menu will be prefixed by this HTML content.
menuPre = ''

# Suffix for the title in navigation menu.
# Default: not set
# The title of the page in the menu will be suffixed by this HTML content.
menuPost = ''

# Link the menu entry to a different internal page instead.
# Default: not set
# This will effectivly hide the page and its content from the viewer by
# linking to the given URL instead.
menuPageRef = ''

# Link the menu entry to an external URL instead of a page.
# Default: not set
# This will effectivly hide the page and its content from the viewer by
# linking to the given URL instead.
menuUrl = ''

# The order of navigation menu submenus.
# Default: 'weight'
# Submenus can be ordered by 'weight', 'title', 'linktitle', 'modifieddate',
# 'expirydate', 'publishdate', 'date', 'length' or 'default' (adhering to
# Hugo's default sort order).
# If not set, the value of the parent menu entry is used.
ordersectionsby = 'weight'

# The initial expand state of submenus.
# Default: not set
# This controls whether submenus will be expanded (true), or collapsed (false)
# in the menu. If not set, the first menu level is set to false, all others
# levels are set to true. If not set, the value of the parent menu entry is used.
# If the displayed page has submenus, they will always been displayed expanded
# regardless of this option.
alwaysopen = ''

# Shows expander for submenus.
# Default: false
# If set to true, a submenu in the sidebar will be displayed in a collapsible
# tree view and a clickable expander is set in front of the entry.
# Note that if set to `true` can have a major performance impact on build
# for sites with many pages.
# If not set, the set value of your site's hugo.toml is used.
collapsibleMenu = true

# Define your own sidebar menus.
# Menus are written from the sidebar's top to buttom in the order given in
# these arrays. If not set, the set value of your site's hugo.toml is used.
# Each entry can contain the following keys:
# - `type` is mandatory. Either `page` in case it should generate a tree from
#    the page structure, `menu` in case it should generate a tree from a
#    defined menu, `custom` for arbitrary HTML snippets or `divider` for a
#    horizontal ruler.
# - `identifier` is mandatory. In case of `type=page`, anything can be used,
#    in case of `type=menu` the `identifier` key must be identical to the
#    key of the menu definition.
# - `main`, boolean. If `true`, the first tree level is spaced more generous
#    and the text is emphasized. Default: `true` for `type=page` and `false`
#    for `type=menu` and `type=custom`
# - `disableTitle`, boolean. If `true`, there is no title above the tree.
#    Default: `true` for `type=page` and `false` for `type=menu`. If a title
#    should be used, in case of `type=page` it will be taken from the page's
#    `menuTitle` front matter and if not set, from the translation files, using
#    the menu `identifier` as key. In case of `type=menu` it will be taken
#    from the menu `title` according to Hugo's documentation and if not set
#    from the menu `name` and if this is not set form the page's `linkTitle`.
# - `pageRef`, optional. In case of `type=page` this is the starting page's
#    path. If not set, the home page will be used.
# - `elements`, optional. In case of `type=custom` the list of elements to
#    display. The theme shipps with the following predefined snippets which
#    all accept the `icon` parameter to overwrite the default icon
#    - languageswitcher: will display the language switcher
#    - variantswitcher: will display the variant switcher
#    - versionswitcher: will display the version switcher
#    - historyclearer: will display a button to clear the history of visited links

# The sidebar header menu.
# Default: see notes
# If not given, defaults to
# - a home button if configured; if you redefine this, use a Hugo menu and a type=menu to replicate this
# - a divider to separate from the sidebarmenus (depending on the configuration of the theme variant)
sidebarheadermenus = ''

# The main sidebar header.
# Default: see notes
# - the main page menu based on your content structure
# - the shortcuts menu including the title if configured
sidebarmenus = ''

# The main sidebar header.
# Default: see notes
# - a divider to separate from the sidebarmenus if any of the following is configured
# - the language switcher if multilingual is configured
# - the variant switcher if multiple variants are configured
# - the history clearer if you configured to mark visited pages
sidebarfootermenus = ''

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Hidden pages
# These options configure how hidden pages are treated.
# A page flagged as hidden, is only removed from the navigation menu if you are
# currently not on this page or the hidden page is not part of current page's
# ancestors. For all other functionality in Hugo a hidden page behaves like any
# other page if not otherwise configured.

# Hide a page's menu entry.
# Default: false
# If this value is true, the page is hidden from the menu.
hidden = false

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Content
# These options modify how your content is displayed.

# Prefix for the title in the content area.
# Default: not set
# The title of the page heading will be prefixed by this HTML content.
headingPre = ''

# Suffix for the title in the content area.
# Default: not set
# The title of the page heading will be suffixed by this HTML content.
headingPost = ''

# Display name of the page's last editor.
# Default: not set
# If set, it will be displayed in the default footer.
LastModifierDisplayName = ''

# Email address of the page's last editor.
# Default: not set
# If set together with LastModifierDisplayName, it will be displayed in the
# default footer.
LastModifierEmail = ''

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Highlight
# These options configure how code is displayed.

# Wrap for code blocks.
# Default: true
# By default lines of code blocks wrap around if the line is too long to be
# displayed on screen. If you dislike this behavior, you can reconfigure it
# here.
# Note that lines always wrap in print mode regardless of this option.
# If not set, the set value of your site's hugo.toml is used or given as a
# parameter to individual code blocks.
highlightWrap = true

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Include
# These options configure how the include shortcode works.

# What to do when path is not resolved.
# Default: ''
# You can control what should happen if a path can not be resolved to as
# a resource or via the file system. If not set, no output will be written
# for the unresolved path. If set to `warning` the same happens and an additional
# warning is printed. If set to `error` an error message is printed and the build
# is aborted.
# If not set, the set value of your site's hugo.toml is used.
include.errorlevel = ''

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Images
# These options configure how images are displayed.

# What to do when local image link is not resolved.
# Default: ''
# You can control what should happen if a local image can not be resolved to as
# a resource. If not set, the unresolved link is written as given into the resulting
# output. If set to `warning` the same happens and an additional warning is
# printed. If set to `error` an error message is printed and the build is
# aborted.
# Please note that this can not resolve files inside of your `static` directory.
# If not set, the set value of your site's hugo.toml is used.
image.errorlevel = ''

# Image effects.
# See the documentation for how you can even add your own arbitrary effects to
# the list.
# All effect values default to the values of your site's hugo.toml and can be
# overridden through URL parameter given to the image. See the documentation for
# details.

# Default: false
imageEffects.border = true
# Default: false
imageEffects.dataurl = false
# Default: false
imageEffects.inlinecontent = false
# Default: true
imageEffects.lazy = true
# Default: true
imageEffects.lightbox = true
# Default: false
imageEffects.shadow = false

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Links
# These options configure how links are displayed.

# How to open external links.
# Default: '_blank'
# For external links you can define how they are opened in your browser. All
# values for the HTML `target` attribute of the `a` element are allowed. The
# default value opens external links in a separate browser tab. If you want
# to open those links in the same tab, use '_self'.
# If you want to set the default behavior for all links, use link effects.
# If not set, the set value of your site's hugo.toml is used.
externalLinkTarget = '_self'

# What to do when local page link is not resolved.
# Default: ''
# You can control what should happen if a local link can not be resolved to a
# page. If not set, the unresolved link is written as given into the resulting
# output. If set to `warning` the same happens and an additional warning is
# printed. If set to `error` an error message is printed and the build is
# aborted.
# Please note that with Hugo < 0.123.0 + `uglyURLs=true` this can lead to false
# negatives.
# If not set, the set value of your site's hugo.toml is used.
link.errorlevel = ''

# Link effects.
# See the documentation for how you can even add your own arbitrary effects to
# the list.
# All effect values default to the values of your site's hugo.toml and can be
# overridden through URL parameter given to the link. See the documentation for
# details.

# Default: false
linkEffects.download = false
# Default: false
linkEffects.target = false

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# MathJax
# These options configure how math formulae are displayed.

# Initialization options for MathJax.
# Default: not set
# A JSON value. See the MathJaxdocumentation for possible parameter.
# If not set, the set value of your site's hugo.toml is used.
mathJaxInitialize = '{}'

# Force load Math on every page.
# Default: false
# If a Math shortcode or codefence is found, the option will be ignored and
# Math will be loaded regardlessly. This option is useful in case you
# are using passthrough configuration to render your math. In this case no shortcode or
# codefence is involved and the library is not loaded by default so you can
# force loading it by setting `math.force=true`.
# This option has an alias `math=true`.
# If not set, the set value of your site's hugo.toml is used.
math.force = false

# URL for external MathJax library.
# Default: not set
# Specifies the remote location of the MathJax library. By default the shipped
# version will be used.
# If not set, the set value of your site's hugo.toml is used.
customMathJaxURL = '' # 'https://unpkg.com/mathjax/es5/tex-mml-chtml.js'

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Mermaid
# These options configure how Mermaid graphs are displayed.

# Make graphs panable and zoomable
# Default: false
# For huge graphs it can be helpful to make them zoomable. Zoomable graphs come
# with a reset button for the zoom.
# If not set, the set value of your site's hugo.toml is used or given as a
# parameter to individual graphs.
mermaidZoom = true

# Initialization options for Mermaid.
# Default: not set
# A JSON value. See the Mermaid documentation for possible parameter.
# If not set, the set value of your site's hugo.toml is used.
mermaidInitialize = '{ "securityLevel": "loose" }'

# Force load Mermaid on every page.
# Default: false
# If a Mermaid shortcode or codefence is found, the option will be ignored and
# Mermaid will be loaded regardlessly. This option is useful in case you
# are using scripting to render your graph. In this case no shortcode or
# codefence is involved and the library is not loaded by default so you can
# force loading it by setting `mermaid.force=true`.
# If not set, the set value of your site's hugo.toml is used.
mermaid.force = false

# URL for external Mermaid library.
# Default: not set
# Specifies the remote location of the Mermaid library. By default the shipped
# version will be used.
# If not set, the set value of your site's hugo.toml is used.
customMermaidURL = '' # 'https://unpkg.com/mermaid/dist/mermaid.min.js'

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# OpenApi
# These options configure how OpenAPI specifications are displayed.

# Load OpenAPI on every page.
# Default: false
# If a OpenAPI shortcode or codefence is found, the option will be ignored and
# OpenAPI will be loaded regardlessly. This option is useful in case you
# are using scripting to render your spec. In this case no shortcode or
# codefence is involved and the library is not loaded by default so you can
# force loading it by setting `openapi.force=true`.
# If not set, the set value of your site's hugo.toml is used.
openapi.force = false

# URL for external OpenAPI library.
# Default: not set
# Specifies the remote location of the OpenAPI library. By default the shipped
# version will be used.
# If not set, the set value of your site's hugo.toml is used.
customOpenapiURL = '' # 'https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js'

# What to do when a local OpenAPI spec link is not resolved.
# Default: ''
# You can control what should happen if a local OpenAPI spec link can not be resolved
# to a resource. If not set, the unresolved link is written as given into the resulting
# output. If set to `warning` the same happens and an additional warning is
# printed. If set to `error` an error message is printed and the build is
# aborted.
# Please note that this can not resolve files inside of your `static` directory.
# If not set, the set value of your site's hugo.toml is used.
openapi.errorlevel = ''
+++

Meta Information

Page Title

The title will be used in the heading and meta information of your HTML.

A page without a title is treated as if hidden=true has been set.

​
+++
title = 'Example Title'
+++
---
title: Example Title
---
{
   "title": "Example Title"
}

Page Description

The description is used for generating HTML meta information, in the children shortcode and in social media meta information.

If not set, the set value of your site’s hugo.toml is used for the HTML meta information and social media meta information. It appears empty for the children shortcode.

​
+++
description = 'Some lenghty example description'
+++
---
description: Some lenghty example description
---
{
   "description": "Some lenghty example description"
}

Social Media Images

The theme adds social media meta tags including feature images for the Open Graph protocol and Twitter Cards to your site. These are configured as mentioned in the linked Hugo docs.

​
+++
images = ['images/hero.png']
+++
---
images:
- images/hero.png
---
{
   "images": [
      "images/hero.png"
   ]
}

Hidden

Front Matter You can hide your pages from the menu by setting hidden=true.

Menu For Hugo menus, you have to set params.hidden=true instead.

See how you can further configure visibility throughout your site.

​
+++
[params]
  hidden = true
+++
---
params:
  hidden: true
---
{
   "params": {
      "hidden": true
   }
}

Add Icon to the Title Heading

Front Matter In the page front matter, add a headingPre to insert any HTML code before the title heading. You can also set headingPost to insert HTML code after the title heading.

You also may want to apply further CSS in this case.

​
+++
[params]
  headingPre = '<i class="fab fa-github"></i> '
+++
---
params:
  headingPre: '<i class="fab fa-github"></i> '
---
{
   "params": {
      "headingPre": "\u003ci class=\"fab fa-github\"\u003e\u003c/i\u003e "
   }
}

Front Matter If you use the default layouts/partials/content-footer.html is not overridden by you, it will display authoring information, namely

See how to further configure this information on a site-wide basis.

​
+++
[params]
  LastModifierDisplayName = 'Santa Claus'
  LastModifierEmail = 'santa@example.com'
  date = 2000-12-24T00:00:00-12:00
+++
---
params:
  LastModifierDisplayName: Santa Claus
  LastModifierEmail: santa@example.com
  date: 2000-12-24T00:00:00-12:00
---
{
   "params": {
      "LastModifierDisplayName": "Santa Claus",
      "LastModifierEmail": "santa@example.com",
      "date": "2000-12-24T00:00:00-12:00"
   }
}

Markdown Syntax

Let’s face it: Writing content for the web is tiresome. WYSIWYG editors help alleviate this task, but they generally result in horrible code, or worse yet, ugly web pages.

Markdown is a better way to write HTML, without all the complexities and ugliness that usually accompanies it.

Some of the key benefits are:

  1. Markdown is simple to learn, with minimal extra characters so it’s also quicker to write content.
  2. Less chance of errors when writing in Markdown.
  3. Produces valid HTML output.
  4. Keeps the content and the visual display separate, so you cannot mess up the look of your site.
  5. Write in any text editor or Markdown application you like.
  6. Markdown is a joy to use!

John Gruber, the author of Markdown, puts it like this:

The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. While Markdown’s syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown’s syntax is the format of plain text email. John Gruber

Tip

Bookmark this page for easy future reference!

Standard and Extensions

If not otherwise noted, the shown examples adhere to the CommonMark standard. In addition the theme supports the following extensions that can be activated in your hugo.toml or are built into the theme:

Paragraphs

In Markdown your content usually spans the whole available document width. This is called a block. Blocks are always separated by whitespace to their adjacent blocks in the resulting document.

Any text not starting with a special sign is written as normal, plain text paragraph block and must be separated to its adjacent blocks by empty lines.

Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus.

Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.
Result

Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus.

Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.

Headings

A good idea is to structure your content using headings and subheadings. HTML-headings from h1 through h6 are constructed with a # for each level.

In Hugo you usually don’t use h1 as this is generated by your theme and you should only have one such element in a document.

# h1 Heading

## h2 Heading

### h3 Heading

#### h4 Heading

##### h5 Heading

###### h6 Heading
Result

h1 Heading

h2 Heading

h3 Heading

h4 Heading

h5 Heading
h6 Heading

Horizontal Rules

To further structure your content you can add horizontal rules. They create a “thematic break” between paragraph blocks. In Markdown, you can create it with three consecutive dashes ---.

Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus.

---

Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.
Result

Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus.

Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.

Blockquotes

Quotations

For quoting blocks of content from another source within your document add > before any text you want to quote.

Blockquotes can also be nested.

> Donec massa lacus, ultricies a ullamcorper in, fermentum sed augue. Nunc augue, aliquam non hendrerit ac, commodo vel nisi.
>
> > Sed adipiscing elit vitae augue consectetur a gravida nunc vehicula. Donec auctor odio non est accumsan facilisis. Aliquam id turpis in dolor tincidunt mollis ac eu diam.
>
> Mauris sit amet ligula egestas, feugiat metus tincidunt, luctus libero. Donec congue finibus tempor. Vestibulum aliquet sollicitudin erat, ut aliquet purus posuere luctus.
Result

Donec massa lacus, ultricies a ullamcorper in, fermentum sed augue. Nunc augue, aliquam non hendrerit ac, commodo vel nisi.

Sed adipiscing elit vitae augue consectetur a gravida nunc vehicula. Donec auctor odio non est accumsan facilisis. Aliquam id turpis in dolor tincidunt mollis ac eu diam.

Mauris sit amet ligula egestas, feugiat metus tincidunt, luctus libero. Donec congue finibus tempor. Vestibulum aliquet sollicitudin erat, ut aliquet purus posuere luctus.

GitHub Alerts

GFM Since Hugo 0.132.0 GitHub alerts are also supported. Please note, that coloring and icons of severities may defer between GitHub and this theme.

If you are in need of more advanced options to style your alerts, like icons, use the notice shortcode.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!INFO]
> Information that users <ins>_might_</ins> find interesting.

> [!NOTE]
> Useful information that users should know, even when skimming content.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.
Result
Caution

Advises about risks or negative outcomes of certain actions.

Important

Key information users need to know to achieve their goal.

Info

Information that users might find interesting.

Note

Useful information that users should know, even when skimming content.

Tip

Helpful advice for doing things better or more easily.

Warning

Urgent info that needs immediate user attention to avoid problems.

Obsidian Callouts

Obsidian Since Hugo 0.134.0 Obsidian callouts are also supported. Which enables configurable title text and expand/collapse.

If you are in need of more advanced options to style your alerts, like icons, use the notice shortcode.

> [!tip] Callouts can have **custom** titles
> Like this one.

> [!tip] Title-only callout

> [!note]- Are callouts foldable?
> Yes! In a foldable callout, the contents are hidden when the callout is collapsed

> [!note]+ Are callouts foldable?
> Yes! In a foldable callout, the contents are hidden when the callout is collapsed
Result
Callouts can have custom titles

Like this one.

Title-only callout
Are callouts foldable?

Yes! In a foldable callout, the contents are hidden when the callout is collapsed

Are callouts foldable?

Yes! In a foldable callout, the contents are hidden when the callout is collapsed

Text Markers

Bold

You can show importance of a snippet of text with a heavier font-weight by enclosing it with two asterisks **.

I am rendered with **bold text**
Result

I am rendered with bold text

Italics

You can emphasize a snippet of text with italics by enclosing it with underscores _.

I am rendered with _italicized text_
Result

I am rendered with italicized text

Marked Text

You can mark text in the predefined accent color of your stylesheet.

Hugo Since Hugo 0.126.0, you can activate this through the Hugo Extra Extension in your hugo.toml

==Parts== of this text ==are marked!==

HTML You can also use it by configuring Hugo for usage of HTML.

<mark>Parts</mark> of this text <mark>are marked!</mark>
Result

Parts of this text are marked!

Inserted Text

You can mark text additions to existing text.

Hugo Since Hugo 0.126.0, you can activate this through the Hugo Extra Extension in your hugo.toml

The ++hot, new++ stuff

HTML You can also use it by configuring Hugo for usage of HTML.

The <ins>hot, new</ins> stuff
Result

The hot, new stuff

Deleted Text

GFM You can do strikethroughs by enclosing text with two tildes ~~. See Hugo’s documentation remarks if you want to use this together with the subscript syntax.

~~Strike through~~ this text
Result

Strike through this text

Special Typesetting

Text Substitution

Pants You can combine multiple punctuation characters to single typographic entities. This will only be applied to text outside of code blocks or inline code.

Double quotes `"` and single quotes `'` of enclosed text are replaced by **"double curly quotes"** and **'single curly quotes'**.

Double dashes `--` and triple dashes `---` are replaced by en-dash **--** and em-dash **---** entities.

Double arrows pointing left `<<` or right `>>` are replaced by arrow **<<** and **>>** entities.

Three consecutive dots `...` are replaced by an ellipsis **...** entity.
Result

Double quotes " and single quotes ' of enclosed text are replaced by “double curly quotes” and ‘single curly quotes’.

Double dashes -- and triple dashes --- are replaced by en-dash – and em-dash — entities.

Double arrows pointing left << or right >> are replaced by arrow « and » entities.

Three consecutive dots ... are replaced by an ellipsis … entity.

Subscript and Superscript

You can also use subscript and superscript text. For more complex stuff, you can use the math shortcode.

Hugo Since Hugo 0.126.0, you can activate this through the Hugo Extra Extension in your hugo.toml

How many liters H~2~O fit into 1dm^3^?

HTML You can also use it by configuring Hugo for usage of HTML.

How many liters H<sub>2</sub>O fit into 1dm<sup>3</sup>?
Result

How many liters H2O fit into 1dm3?

Keyboard Shortcuts

HTML You can use the <kbd> element to style keyboard shortcuts.

Press <kbd>STRG</kbd> <kbd>ALT</kbd> <kbd>DEL</kbd> to end your shift early.
Result

Press STRG ALT DEL to end your shift early.

Lists

Unordered

You can write a list of items in which the order of the items does not explicitly matter.

It is possible to nest lists by indenting an item for the next sublevel.

You may use any of -, * or + to denote bullets for each list item but should not switch between those symbols inside one whole list.

- Lorem ipsum dolor sit amet
- Consectetur adipiscing elit
  - Vestibulum laoreet porttitor sem
  - Ac tristique libero volutpat at
- Nulla volutpat aliquam velit
  - Phasellus iaculis neque
  - Purus sodales ultricies
- Faucibus porta lacus fringilla vel
Result
  • Lorem ipsum dolor sit amet
  • Consectetur adipiscing elit
    • Vestibulum laoreet porttitor sem
    • Ac tristique libero volutpat at
  • Nulla volutpat aliquam velit
    • Phasellus iaculis neque
    • Purus sodales ultricies
  • Faucibus porta lacus fringilla vel

Ordered

You can create a list of items in which the order of items does explicitly matter.

It is possible to nest lists by indenting an item for the next sublevel.

Markdown will automatically number each of your items consecutively. This means, the order number you are providing is irrelevant.

1. Lorem ipsum dolor sit amet
3. Consectetur adipiscing elit
    1. Integer molestie lorem at massa
    7. Facilisis in pretium nisl aliquet
99. Nulla volutpat aliquam velit
    1. Faucibus porta lacus fringilla vel
    1. Aenean sit amet erat nunc
17. Eget porttitor lorem
Result
  1. Lorem ipsum dolor sit amet
  2. Consectetur adipiscing elit
    1. Integer molestie lorem at massa
    2. Facilisis in pretium nisl aliquet
  3. Nulla volutpat aliquam velit
    1. Faucibus porta lacus fringilla vel
    2. Aenean sit amet erat nunc
  4. Eget porttitor lorem

Tasks

GFM You can add task lists resulting in checked or unchecked non-clickable items

- [x] Basic Test
- [ ] More Tests
  - [x] View
  - [x] Hear
  - [ ] Smell
Result
  • Basic Test
  • More Tests
    • View
    • Hear
    • Smell

Tree

Relearn You can add lists as a tree with configurable icons and colors.

The name can be followed by an optional pipe (|) to define an icon and further optional pipe to define the icon’s color.

More details can be found in the tree shortcode docs.

```tree
- home | folder
  - .config | folder
  - My Documents | folder | gold
    - index.html
    - resume.odt | file-word | #df6f40
  - Images | folder
    - pic1.jpg
    - pic2.jpg | file-image | secondary
  - Code | folder
    - home.php | fa-fw fab fa-php | #888cc4
```
Result
  • home
    • .config
    • My Documents
      • index.html
      • resume.odt
    • Images
      • pic1.jpg
      • pic2.jpg
    • Code
      • home.php

Definitions

PHP Definition lists are made of terms and definitions of these terms, much like in a dictionary.

A definition list in Markdown Extra is made of a single-line term followed by a colon and the definition for that term. You can also associate more than one term to a definition.

If you add empty lines around the definition terms, additional vertical space will be generated. Also multiple paragraphs are possible

Apple
: Pomaceous fruit of plants of the genus Malus in the family Rosaceae.
: An American computer company.

Orange
: The fruit of an evergreen tree of the genus Citrus.

  You can make juice out of it.
: A telecommunication company.

  You can't make juice out of it.
Result
Apple
Pomaceous fruit of plants of the genus Malus in the family Rosaceae.
An American computer company.
Orange
The fruit of an evergreen tree of the genus Citrus.

You can make juice out of it.

A telecommunication company.

You can’t make juice out of it.

Code

Inline Code

Inline snippets of code can be wrapped with backticks `.

In this example, `<div></div>` is marked as code.
Result

In this example, <div></div> is marked as code.

Indented Code Block

A simple code block can be generated by indenting several lines of code by at least two spaces.

Be impressed by my advanced code:

    // Some comments
    line 1 of code
    line 2 of code
    line 3 of code
Result

Be impressed by my advanced code:

// Some comments
line 1 of code
line 2 of code
line 3 of code

Fenced Code Block

If you want to gain more control of your code block you can enclose your code by at least three backticks ``` a so called fence.

GFM You can also add a language specifier directly after the opening fence, ```js, and syntax highlighting will automatically be applied according to the selected language in the rendered HTML.

See Code Highlighting for additional documentation.

```js
{
    name: "Claus",
    surname: "Santa",
    profession: "courier",
    age: 666,
    address: {
        city: "North Pole",
        postalCode: 1,
        country: "Arctic"
    },
    friends: [ "Dasher", "Dancer", "Prancer", "Vixen", "Comet", "Cupid", "Donder", "Blitzen", "Rudolph" ]
};
```
Result 
{
    name: "Claus",
    surname: "Santa",
    profession: "courier",
    age: 666,
    address: {
        city: "North Pole",
        postalCode: 1,
        country: "Arctic"
    },
    friends: [ "Dasher", "Dancer", "Prancer", "Vixen", "Comet", "Cupid", "Donder", "Blitzen", "Rudolph" ]
};

Tables

GFM You can create tables by adding pipes as dividers between each cell, and by adding a line of dashes (also separated by bars) beneath the header. Note that the pipes do not need to be vertically aligned.

| Option | Description |
|--------|-------------|
| data   | path to data files to supply the data that will be passed into templates. |
| engine | engine to be used for processing templates. Handlebars is the default. |
| ext    | extension to be used for dest files. |
Result
Option Description
data path to data files to supply the data that will be passed into templates.
engine engine to be used for processing templates. Handlebars is the default.
ext extension to be used for dest files.

Aligned Columns

Adding a colon on the left and/or right side of the dashes below any heading will align the text for that column accordingly.

| Option | Number | Description |
|-------:|:------:|:------------|
| data   | 1      | path to data files to supply the data that will be passed into templates. |
| engine | 2      | engine to be used for processing templates. Handlebars is the default. |
| ext    | 3      | extension to be used for dest files. |
Result
Option Number Description
data 1 path to data files to supply the data that will be passed into templates.
engine 2 engine to be used for processing templates. Handlebars is the default.
ext 3 extension to be used for dest files.

GFM Absolute URLs will automatically be converted into a link.

This is a link to https://example.com.
Result

This is a link to https://example.com.

You can explicitly define links in case you want to use non-absolute URLs or want to give different text.

[Assemble](http://assemble.io)
Result

Assemble

For even further information, you can add an additional text, displayed in a tooltip on hovering over the link.

[Upstage](https://github.com/upstage/ "Visit Upstage!")
Result

Upstage

Links can be simplyfied for recurring reuse by using a reference ID to later define the URL location. This simplyfies writing if you want to use a link more than once in a document.

[Example][somelinkID]

[somelinkID]: https://example.com "Go to example domain"
Result

Example

Footnotes

PHP Footnotes work mostly like reference-style links. A footnote is made of two things, a marker in the text that will become a superscript number and a footnote definition that will be placed in a list of footnotes.

Usually the list of footnotes will be shown at the end of your document. If we use a footnote in a notice box it will instead be listed at the end of its box.

Footnotes can contain block elements, which means that you can put multiple paragraphs, lists, blockquotes and so on in a footnote. It works the same as for list items, just indent the following paragraphs by four spaces in the footnote definition.

That's some text with a footnote[^1]

[^1]: And that's the footnote.

That's some more text with a footnote.[^someid]

[^someid]:
    Anything of interest goes here.

    Blue light glows blue.
Result

That’s some text with a footnote1

That’s some more text with a footnote.2

  1. And that’s the footnote. ↩︎

  2. Anything of interest goes here.

    Blue light glows blue. ↩︎

Relearn This theme allows additional non-standard formatting by setting query parameter at the end of the URL. See the link effects docs for a detailed example and how to configure it.

Target

Add query parameter target=_self or target=_blank to override site-wide settings of the target behavior individuallly for each link.

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

Magic in new window

Download

Add query parameter download or download=myfile.gif to force your browser to download the link target instead of opening it.

[Magic as a download](images/magic.gif?download)
Result

Magic as a download

Images

Basic Images

Images have a similar syntax to links but include a preceding exclamation mark.

![Spock](https://octodex.github.com/images/spocktocat.png)
Result

Spock Spock

Image with Tooltip

Like links, images can also be given a tooltip.

![Picard](https://octodex.github.com/images/jean-luc-picat.jpg "Jean Luc Picard")
Result

Picard Picard

Image References

Images can also be linked by reference ID to later define the URL location. This simplyfies writing if you want to use an image more than once in a document.

![La Forge][laforge]

[laforge]: https://octodex.github.com/images/trekkie.jpg "Geordi La Forge"
Result

La Forge La Forge

Image Effects

Relearn This theme allows additional non-standard formatting by setting query parameter at the end of the image URL. See the image effects docs for a detailed example and how to configure it.

Resizing

Add query parameter width and/or height to the link image to resize the image. Values are CSS values (default is auto).

![Minion](https://octodex.github.com/images/minion.png?width=20vw)
Result

Minion Minion

![Minion](https://octodex.github.com/images/minion.png?height=50px)
Result

Minion Minion

![Minion](https://octodex.github.com/images/minion.png?height=50px&width=40vw)
Result

Minion Minion

CSS Classes

Add a query parameter classes to the link image to add CSS classes. Add some of the predefined values or even define your own in your CSS.

Shadow
![Spidertocat](https://octodex.github.com/images/spidertocat.png?classes=shadow)
Result

Spidertocat Spidertocat

Border
![DrOctocat](https://octodex.github.com/images/droctocat.png?classes=border)
Result

DrOctocat DrOctocat

Left
![Supertocat](https://octodex.github.com/images/okal-eltocat.jpg?classes=left)
Result

Supertocat Supertocat

![Riddlocat](https://octodex.github.com/images/riddlocat.jpg?classes=right)
Result

Riddlocat Riddlocat

Inline
![Spidertocat](https://octodex.github.com/images/spidertocat.png?classes=inline)
![DrOctocat](https://octodex.github.com/images/droctocat.png?classes=inline)
![Supertocat](https://octodex.github.com/images/okal-eltocat.jpg?classes=inline)
![Riddlocat](https://octodex.github.com/images/riddlocat.jpg?classes=inline)
Result

Spidertocat Spidertocat DrOctocat DrOctocat Supertocat Supertocat Riddlocat Riddlocat

Combination
![X-tocat](https://octodex.github.com/images/xtocat.jpg?classes=shadow,border,left)
Result

X-tocat X-tocat

Add the query parameter lightbox=false to the image link to disable the lightbox.

![Homercat](https://octodex.github.com/images/homercat.png?lightbox=false)
Result

Homercat

Note

If you want to wrap an image in a link and lightbox=true is your default setting, you have to explicitly disable the lightbox to avoid it to hijacking your link like:

[![Homercat](https://octodex.github.com/images/homercat.png?lightbox=false)](https://octodex.github.com/#homercat)

Homercat

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 the URL is external and externalLinkTarget is set, it replaces the value of the link effect configured on the same level (eg. in your hugo.toml or in the page’s front matter). Nervertheless the resulting value can still be overwritten by 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.

Effect Priority

Link effects are applied in the following priority order (lowest to highest):

  1. Built-in defaults
  2. Site-wide configuration in hugo.toml
  3. Page front matter configuration
  4. URL query parameters
  5. Template caller attributes parameter (highest priority)

Explicitly set URL query parameter will override the defaults set for a page or your site. When calling the link partial directly from templates, effects passed via the attributes parameter have the highest priority and will override all other settings.

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

​
+++
[params]
  [params.linkEffects]
    target = '_blank'
+++
---
params:
  linkEffects:
    target: _blank
---
{
   "params": {
      "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

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

Template Usage

When calling the link partial directly from templates, you can pass effect preferences via the attributes parameter. Effect names can be prefixed with no to disable them.

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

This approach has the highest priority and will override all other effect settings, including URL query parameters. Effect classes are processed but not added to the final HTML class attribute. Non-effect classes pass through unchanged.

For example, class = "download custom-link-class" will enable the download effect and add custom-link-class to the HTML output, but download will not appear in the final class attribute.

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.

Effect Priority

Image effects are applied in the following priority order (lowest to highest):

  1. Built-in defaults
  2. Site-wide configuration in hugo.toml
  3. Page front matter configuration
  4. URL query parameters
  5. Template caller attributes parameter (highest priority)

Explicitly set URL query parameter will override the defaults set for a page or your site. When calling the image partial directly from templates, effects passed via the attributes parameter have the highest priority and will override all other settings.

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

​
+++
[params]
  [params.imageEffects]
    lazy = false
+++
---
params:
  imageEffects:
    lazy: false
---
{
   "params": {
      "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

​
[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 calling the image partial directly from templates, you can pass effect preferences via the attributes parameter. Effect names can be prefixed with no to disable them.

​
{{- $attributes := dict "class" "nolightbox border" }}
{{ partial "shortcodes/image.html" (dict "page" . "url" "image.png" "attributes" $attributes) }}

This approach has the highest priority and will override all other effect settings, including URL query parameters. Effect classes are processed but not added to the final HTML class attribute. Non-effect classes pass through unchanged.

For example, class = "nolightbox custom-img-class" will disable the lightbox effect and add custom-img-class to the HTML output, but neither lightbox nor nolightbox will appear in the final class attribute.