Subsct'ns o' Rambl'n

Directory Structure

In Cap'n Hugo, planks be th' core o' yer ship.

Th' theme generates th' navigat'n menu out o' th' given directory structure.

Org'nize yer ship like any other Cap'n Hugo project. Typically, ye will have a rrrambl'n directory wit' all yer planks.

  • rrrambl'n
    • 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
Avast

While ye can also go different, _index.md (with an underscore) be recommended fer each directory, it’s yer directory’s home plank.

See Hugo’s guide fer rrrambl'n t' learn more.

Front Matter

Plank Designs

How t' vary layouts by us'n plank designs

Menus

Sett'n th' behavior o' th' menus

Link'n

What opt'ns be avail'ble fer links an' images

Topbar

Configure th' topbar

Reference

All front matter fer th' Relearrrn theme

Subsct'ns o' Front Matter

Page Designs

Plank designs be used t' provide different layouts fer yer planks.

A plank be displayed by exactly one plank design an' be represented by Hugo’s reserved type front matter.

Th' Relearrrn theme ships wit' th' plank designs home, chapter, an' default fer th' HTML output format but ye can define further custom plank designs.

Us'n a Plank Design

Regardless o' shipped or custom plank design, ye be us'n them 'n th' same way.

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

    hugo new --kind chapter log/_index.md

  • If ye be creat'n yer Marrrkdown files manually, ye can achieve th' same by just sett'n type='chapter' 'n th' front matter t' make yer plank displayed wit' th' chapter plank design.

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

If no type be set 'n yer front matter or th' plank design doesn’t exist fer a given output format, th' plank be treated as if type='default' was set.

Predefined Designs fer th' HTML Output Format

Home

A Home plank be th' start'n plank o' yer project. It’s best t' have only one plank o' this kind 'n yer project.

T' create a home plank, run th' follow'n command

hugo new --kind home _index.md

Home page Home page

Chapter

A Chapter displays a plank meant t' be used as introduct'n fer a set o' child planks.

Commonly, it contains a title front matter an' a short descript'n 'n th' rrrambl'n.

T' create a chapter plank, run th' follow'n command

hugo new --kind chapter log/_index.md

If a numerical weight front matter be set, it will be used t' generate th' subtitle o' th' chapter plank. Set th' number t' a consecutive value start'n at 1 fer each new chapter on th' same directory level.

Chapter page Chapter page

Default

A Default plank be any other rrrambl'n plank.

T' create a default plank, run either one o' th' follow'n 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

Opt'n Front Matter By default, external links open 'n th' same browser tab. T' change this, use th' externalLinkTarget sett'n wit' a proper link target.

T' set default values fer all links, use link effects.

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

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

Opt'n Front Matter Ye can use link.errorlevel an' image.errorlevel t' control what should happen if a local link can not be resolved t' a plank and/or a resource.

If not set or empty, any unresolved link be written as given into th' result'n output. If set t' warning th' same happens an' an additional warning be printed 'n th' built console. If set t' error an error message be printed an' th' build be aborted.

Please note that this can not resolve files inside o' yer static directory. Th' file must be a resource o' th' plank or th' ship.

Link warnings be also avail'ble fer th' include an' openapi shorrrtcodes.

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

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

Ignor'n False Negatives

Opt'n Front Matter In case ye want t' use link warnings but be bothered by false negatives, ye can configure an ignore list o' regular expressions. Th' referenced address will be checked against all regexes o' this list. If th' address matches at least one regex, no output will be written t' th' console. Th' check uses Hugo’s findRE funct'n.

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

Check External URLs

Opt'n Front Matter External URLs can be checked fer validity dur'n build. It will only be checked if th' URL does not match a urlIgnoreCheck pattern.

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

Topbarrr

This plank be about how t' configure th' topbar us'n configurat'n opt'ns. If ye want t' add further buttons or functionality, see this section.

Yer topbar contains th' follow'n elements. Some o' them be configuar'ble:

T'ble o' Contents

Opt'n Front Matter Set disableToc=true t' hide th' TOC button on all planks. If th' button be hidden, also th' keyboard shortcut be disabled. This can be overridden 'n a page’s front matter.

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

Opt'n Front Matter Set disableBreadcrumb=true t' hide th' breadcrumb 'n th' topbar.

Further breadcrumbs sett'ns can be found 'n th' rrrambl'n configurat'n section.

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

Edit Button

Opt'n Front Matter If editURL be set t' a URL, an edit button will be shown 'n th' topbar. If th' button be hidden, also th' keyboard shortcut be disabled.

Th' value can contain th' macro ${FilePath} which will be replaced by th' file path o' yer displayed plank. If no ${FilePath} be given 'n th' value, th' value be treated as if th' ${FilePath} was appended at th' end o' th' value. This can be overridden 'n th' planks 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}"
}

Marrrkdown Button

Opt'n Front Matter Ye can hide th' Marrrkdown button if th' Marrrkdown output format be active by sett'n disableMarkdownButton=true.

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

Source Button

Opt'n Front Matter Ye can hide th' Source button if th' Source output format be active by sett'n disableSourceButton=true.

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

Opt'n Front Matter Ye can hide th' print button if th' print output format be active by sett'n disablePrintButton=true.

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

Arrow Navigat'n

Opt'n Front Matter Ye can hide th' previous/next buttons by sett'n disableNextPrev=true. If th' buttons be hidden, also th' keyboard shortcuts be disabled.

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

Front Matter Reference

Every Cap'n Hugo plank must have front matter.

In addit'n t' Hugo’s standard front matter, th' Relearrrn theme offers extras sett'ns listed here.

Throughout th' documentat'n, theme-specific front matter be marked wit' a Front Matter badge.

Add theme front matter directly t' th' root o' yer 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 o' all avail'ble front matter wit' example values. Default values be described 'n th' annotated example below or 'n each front matter’s documentat'n.

​
+++
[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 opt'n value be said t' be not set, ye can achieve th' same behavior
# by giv'n it an empty str'n value.

###############################################################################
# Cap'n Hugo
# These opt'ns usually apply t' other themes as well.

# Th' social media image o' yer plank.
# Default: not set
# This be used fer generat'n social media meta informat'n fer th' opengraph
# protocol an' twitter cards.
# If not set, th' set value o' yer site's hugo.toml be used.
# images = [ 'images/hero.png' ]

# Th' title o' yer plank.
# Default: not set
# A plank without a title be treated as a hidden plank.
# title = 'Example Page'

# Th' descript'n o' yer plank.
# Default: not set
# This be used fer generat'n HTML meta tags, social media meta informat'n
# fer th' opengraph protocol an' twitter cards.
# If not set, th' set value o' yer site's hugo.toml be used fer th' html
# meta tag, social media meta informat'n fer th' opengraph protocol an'
# twitter cards.
# descript'n = ''

# Th' plank design t' be used
# Default: not set
# This decides th' layout o' yer plank. Th' theme ships 'home', 'chapter' an'
# 'default'. If not set, 'default' be taken.
# type = ''

###############################################################################
# Relearrrn Theme
# These opt'ns be specific t' th' Relearrrn theme.

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# General
# These opt'ns be defin'n general, non visual behavior.

# Conditionally ignore errorlevel sett'ns
# Default: []
# Th' theme supports check'n referenced address (e.g. wit'
# link.errorlevel, image.errorlevel, etc. see below). Sometimes checks lead
# t' console output due t' false negatives. Ye can turn off th' checks
# fer individual referenced addresses by defin'n regular expressions here.
# Th' referenced address will be checked against all regexes o' this array.
# If it matches at least one, no output will be written t' th' console.
# This array can be expanded globally 'n yer site's hugo.toml.
urlIgnoreCheck = []

# Check external URLs
# Default: false
# If `true` th' theme checks dur'n build if an external URL be reach'ble.
# If it fails, it write errors accord'n t' th' errorlevel sett'ns. A check
# be omitted if th' URL be found 'n th' `urlIgnoreCheck` list.
# If not set, th' set value o' yer site's hugo.toml be used.
urlExternalCheck = false

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Topbar
# These opt'ns modify th' topbar appearance.

# Hide th' table o' contents button.
# Default: false
# If th' TOC button be hidden, also th' keyboard shortcut be disabled.
# If not set, th' set value o' yer site's hugo.toml be used.
disableToc = false

# Hide th' breadcrumbs.
# Default: false
# If th' breadcrumbs be hidden, th' title o' th' displayed plank will still be
# shown 'n th' topbar.
disableBreadcrumb = false

# Hide th' Marrrkdown button.
# Default: false
# This hides th' Marrrkdown button if ye activated th' Marrrkdown output format.
# If not set, th' set value o' yer site's hugo.toml be used.
disableMarkdownButton = false

# Hide th' Source button.
# Default: false
# This hides th' Source button if ye activated th' Source output format.
# If not set, th' set value o' yer site's hugo.toml be used.
disableSourceButton = false

# Hide th' Print button.
# Default: false
# This hides th' print button if ye activated th' print output format.
# If not set, th' set value o' yer site's hugo.toml be used.
disablePrintButton = false

# Hide Next an' Previous navigat'n buttons.
# Default: false
# If th' navigat'n buttons be hidden, also th' keyboard shortcuts be
# disabled.
disableNextPrev = false

# Th' URL prefix t' edit a plank.
# Default: not set
# If set, an edit button will be shown 'n th' topbar. If th' button be hidden,
# also th' keyboard shortcuts be disabled. Th' value can contain th' macro
# `${FilePath}` which will be replaced by th' file path o' yer displayed plank.
# If not set, th' set value o' yer site's hugo.toml be used. If th' global
# parameter be given but ye want t' hide th' button fer th' displayed plank,
# ye can set th' value t' an empty str'n. If instead o' hid'n ye want t' have
# an disabled button, ye can set th' value t' a str'n contain'n just spaces.
# This be useful if ye want t' give th' opportunity fer people t' create merge
# request fer yer rrrambl'n.
editURL = ''

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Menu
# These opt'ns modify th' menu appearance.

# Menu specific title
# Default: not set
# Th' title displayed 'n th' menu. If not set th' `title` front matter will
# be used.
linkTitle = ''

# Prefix fer th' title 'n navigat'n menu.
# Default: not set
# Th' title o' th' plank 'n th' menu will be prefixed by this HTML rrrambl'n.
menuPre = ''

# Suffix fer th' title 'n navigat'n menu.
# Default: not set
# Th' title o' th' plank 'n th' menu will be suffixed by this HTML rrrambl'n.
menuPost = ''

# Link th' menu entry t' a different internal plank instead.
# Default: not set
# This will effectivly hide th' plank an' its rrrambl'n from th' viewer by
# link'n t' th' given URL instead.
menuPageRef = ''

# Link th' menu entry t' an external URL instead o' a plank.
# Default: not set
# This will effectivly hide th' plank an' its rrrambl'n from th' viewer by
# link'n t' th' given URL instead.
menuUrl = ''

# Th' order o' navigat'n menu submenus.
# Default: 'weight'
# Submenus can be ordered by 'weight', 'title', 'linktitle', 'modifieddate',
# 'expirydate', 'publishdate', 'date', 'length' or 'default' (adher'n t'
# Hugo's default sort order).
# If not set, th' value o' th' parent menu entry be used.
ordersectionsby = 'weight'

# Th' initial expand state o' submenus.
# Default: not set
# This controls whether submenus will be expanded (true), or collapsed (false)
# 'n th' menu. If not set, th' first menu level be set t' false, all others
# levels be set t' true. If not set, th' value o' th' parent menu entry be used.
# If th' displayed plank has submenus, they will always been displayed expanded
# regardless o' this opt'n.
alwaysopen = ''

# Shows expander fer submenus.
# Default: false
# If set t' true, a submenu 'n th' sidebar will be displayed 'n a collaps'ble
# tree view an' a click'ble expander be set 'n front o' th' entry.
# Avast that if set t' `true` can have a major performance impact on build
# fer sites wit' many planks.
# If not set, th' set value o' yer site's hugo.toml be used.
collapsibleMenu = true

# Define yer own sidebar menus.
# Menus be written from th' sidebar's top t' buttom 'n th' order given 'n
# these arrays. If not set, th' set value o' yer site's hugo.toml be used.
# Each entry can contain th' follow'n keys:
# - `type` be mandatory. Either `page` 'n case it should generate a tree from
#    th' plank structure, `menu` 'n case it should generate a tree from a
#    defined menu, `custom` fer arbitrary HTML snippets or `divider` fer a
#    horizontal ruler.
# - `identifier` be mandatory. In case o' `type=page`, anyth'n can be used,
#    'n case o' `type=menu` th' `identifier` key must be identical t' th'
#    key o' th' menu definit'n.
# - `main`, boolean. If `true`, th' first tree level be spaced more generous
#    an' th' text be emphasized. Default: `true` fer `type=page` an' `false`
#    fer `type=menu` an' `type=custom`
# - `disableTitle`, boolean. If `true`, there be no title above th' tree.
#    Default: `true` fer `type=page` an' `false` fer `type=menu`. If a title
#    should be used, 'n case o' `type=page` it will be taken from th' page's
#    `menuTitle` front matter an' if not set, from th' translat'n files, us'n
#    th' menu `identifier` as key. In case o' `type=menu` it will be taken
#    from th' menu `title` accord'n t' Hugo's documentat'n an' if not set
#    from th' menu `name` an' if this be not set form th' page's `linkTitle`.
# - `pageRef`, optional. In case o' `type=page` this be th' start'n page's
#    path. If not set, th' home plank will be used.
# - `elements`, optional. In case o' `type=custom` th' list o' elements t'
#    display. Th' theme shipps wit' th' follow'n predefined snippets which
#    all accept th' `icon` parameter t' overwrite th' default ay'con
#    - languageswitcher: will display th' language switcher
#    - variantswitcher: will display th' variant switcher
#    - versionswitcher: will display th' version switcher
#    - historyclearer: will display a button t' clear th' history o' visited links

# Th' sidebar header menu.
# Default: see notes
# If not given, defaults t'
# - a home button if configured; if ye redefine this, use a Cap'n Hugo menu an' a type=menu t' replicate this
# - a divider t' separate from th' sidebarmenus (depend'n on th' configurat'n o' th' theme variant)
sidebarheadermenus = ''

# Th' main sidebar header.
# Default: see notes
# - th' main plank menu based on yer rrrambl'n structure
# - th' shortcuts menu includ'n th' title if configured
sidebarmenus = ''

# Th' main sidebar header.
# Default: see notes
# - a divider t' separate from th' sidebarmenus if any o' th' follow'n be configured
# - th' language switcher if multilingual be configured
# - th' variant switcher if multiple variants be configured
# - th' history clearer if ye configured t' mark visited planks
sidebarfootermenus = ''

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Hidden planks
# These opt'ns configure how hidden planks be treated.
# A plank flagged as hidden, be only removed from th' navigat'n menu if ye be
# currently not on this plank or th' hidden plank be not part o' current page's
# ancestors. For all other functionality 'n Hugo a hidden plank behaves like any
# other plank if not otherwise configured.

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

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Rrrambl'n
# These opt'ns modify how yer rrrambl'n be displayed.

# Prefix fer th' title 'n th' rrrambl'n area.
# Default: not set
# Th' title o' th' plank head'n will be prefixed by this HTML rrrambl'n.
headingPre = ''

# Suffix fer th' title 'n th' rrrambl'n area.
# Default: not set
# Th' title o' th' plank head'n will be suffixed by this HTML rrrambl'n.
headingPost = ''

# Display name o' th' page's last editor.
# Default: not set
# If set, it will be displayed 'n th' default footer.
LastModifierDisplayName = ''

# Email address o' th' page's last editor.
# Default: not set
# If set together wit' LastModifierDisplayName, it will be displayed 'n th'
# default footer.
LastModifierEmail = ''

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Highlight
# These opt'ns configure how code be displayed.

# Wrap fer code blocks.
# Default: true
# By default lines o' code blocks wrap around if th' line be too long t' be
# displayed on screen. If ye dislike this behavior, ye can reconfigure it
# here.
# Avast that lines always wrap 'n print mode regardless o' this opt'n.
# If not set, th' set value o' yer site's hugo.toml be used or given as a
# parameter t' individual code blocks.
highlightWrap = true

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Include
# These opt'ns configure how th' include shortcode works.

# What t' do when path be not resolved.
# Default: ''
# Ye can control what should happen if a path can not be resolved t' as
# a resource or via th' file system. If not set, no output will be written
# fer th' unresolved path. If set t' `warning` th' same happens an' an additional
# warning be printed. If set t' `error` an error message be printed an' th' build
# be aborted.
# If not set, th' set value o' yer site's hugo.toml be used.
include.errorlevel = ''

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Images
# These opt'ns configure how images be displayed.

# What t' do when local image link be not resolved.
# Default: ''
# Ye can control what should happen if a local image can not be resolved t' as
# a resource. If not set, th' unresolved link be written as given into th' result'n
# output. If set t' `warning` th' same happens an' an additional warning be
# printed. If set t' `error` an error message be printed an' th' build be
# aborted.
# Please note that this can not resolve files inside o' yer `static` directory.
# If not set, th' set value o' yer site's hugo.toml be used.
image.errorlevel = ''

# Image effects.
# See th' documentat'n fer how ye can even add yer own arbitrary effects t'
# th' list.
# All effect values default t' th' values o' yer site's hugo.toml an' can be
# overridden through URL parameter given t' th' image. See th' documentat'n fer
# 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 opt'ns configure how links be displayed.

# How t' open external links.
# Default: '_blank'
# For external links ye can define how they be opened 'n yer browser. All
# values fer th' HTML `target` attribute o' th' `a` element be allowed. Th'
# default value opens external links 'n a separate browser tab. If ye want
# t' open those links 'n th' same tab, use '_self'.
# If ye want t' set th' default behavior fer all links, use link effects.
# If not set, th' set value o' yer site's hugo.toml be used.
externalLinkTarget = '_self'

# What t' do when local plank link be not resolved.
# Default: ''
# Ye can control what should happen if a local link can not be resolved t' a
# plank. If not set, th' unresolved link be written as given into th' result'n
# output. If set t' `warning` th' same happens an' an additional warning be
# printed. If set t' `error` an error message be printed an' th' build be
# aborted.
# Please note that wit' Cap'n Hugo < 0.123.0 + `uglyURLs=true` this can lead t' false
# negatives.
# If not set, th' set value o' yer site's hugo.toml be used.
link.errorlevel = ''

# Link effects.
# See th' documentat'n fer how ye can even add yer own arbitrary effects t'
# th' list.
# All effect values default t' th' values o' yer site's hugo.toml an' can be
# overridden through URL parameter given t' th' link. See th' documentat'n fer
# details.

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

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# MathJax
# These opt'ns configure how math formulae be displayed.

# Initializat'n opt'ns fer MathJax.
# Default: not set
# A JSON value. See th' MathJaxdocumentat'n fer poss'ble parameter.
# If not set, th' set value o' yer site's hugo.toml be used.
mathJaxInitialize = '{}'

# Force board Math on every plank.
# Default: false
# If a Math shortcode or codefence be found, th' opt'n will be ignored an'
# Math will be boarded regardlessly. This opt'n be useful 'n case ye
# be us'n passthrough configurat'n t' render yer math. In this case no shortcode or
# codefence be involved an' th' library be not boarded by default so ye can
# force load'n it by sett'n `math.force=true`.
# This opt'n has an alias `math=true`.
# If not set, th' set value o' yer site's hugo.toml be used.
math.force = false

# URL fer external MathJax library.
# Default: not set
# Specifies th' remote locat'n o' th' MathJax library. By default th' shipped
# version will be used.
# If not set, th' set value o' yer site's hugo.toml be used.
customMathJaxURL = '' # 'https://unpkg.com/mathjax/es5/tex-mml-chtml.js'

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Merrrmaid
# These opt'ns configure how Merrrmaid graphs be displayed.

# Make graphs pan'ble an' zoom'ble
# Default: false
# For huge graphs it can be helpful t' make them zoom'ble. Zoom'ble graphs come
# wit' a reset button fer th' zoom.
# If not set, th' set value o' yer site's hugo.toml be used or given as a
# parameter t' individual graphs.
mermaidZoom = true

# Initializat'n opt'ns fer Merrrmaid.
# Default: not set
# A JSON value. See th' Merrrmaid documentat'n fer poss'ble parameter.
# If not set, th' set value o' yer site's hugo.toml be used.
mermaidInitialize = '{ "securityLevel": "loose" }'

# Force board Merrrmaid on every plank.
# Default: false
# If a Merrrmaid shortcode or codefence be found, th' opt'n will be ignored an'
# Merrrmaid will be boarded regardlessly. This opt'n be useful 'n case ye
# be us'n script'n t' render yer graph. In this case no shortcode or
# codefence be involved an' th' library be not boarded by default so ye can
# force load'n it by sett'n `mermaid.force=true`.
# If not set, th' set value o' yer site's hugo.toml be used.
mermaid.force = false

# URL fer external Merrrmaid library.
# Default: not set
# Specifies th' remote locat'n o' th' Merrrmaid library. By default th' shipped
# version will be used.
# If not set, th' set value o' yer site's hugo.toml be used.
customMermaidURL = '' # 'https://unpkg.com/mermaid/dist/mermaid.min.js'

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# OpenApi
# These opt'ns configure how OpenAPI specificat'ns be displayed.

# Board OpenAPI on every plank.
# Default: false
# If a OpenAPI shortcode or codefence be found, th' opt'n will be ignored an'
# OpenAPI will be boarded regardlessly. This opt'n be useful 'n case ye
# be us'n script'n t' render yer spec. In this case no shortcode or
# codefence be involved an' th' library be not boarded by default so ye can
# force load'n it by sett'n `openapi.force=true`.
# If not set, th' set value o' yer site's hugo.toml be used.
openapi.force = false

# URL fer external OpenAPI library.
# Default: not set
# Specifies th' remote locat'n o' th' OpenAPI library. By default th' shipped
# version will be used.
# If not set, th' set value o' yer site's hugo.toml be used.
customOpenapiURL = '' # 'https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js'

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

Meta Information

Plank Title

Th' title will be used 'n th' head'n an' meta informat'n o' yer HTML.

A plank without a title be treated as if hidden=true has been set.

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

Plank Descript'n

Th' descript'n be used fer generat'n HTML meta informat'n, 'n th' children shortcode an' 'n social media meta informat'n.

If not set, th' set value o' yer site’s hugo.toml be used fer th' HTML meta informat'n an' social media meta informat'n. It appears empty fer th' children shortcode.

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

Social Media Images

Th' theme adds social media meta tags includ'n feature images fer th' Open Graph protocol an' Twitter Cards t' yer ship. These be configured as mentioned 'n th' linked Cap'n Hugo docs.

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

Hidden

Front Matter Ye can hide yer planks from th' menu by sett'n hidden=true.

Menu For Cap'n Hugo menus, ye have t' set params.hidden=true instead.

See how ye can further configure visibility throughout yer ship.

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

Add Ay'con t' th' Title Head'n

Front Matter In th' plank front matter, add a headingPre t' insert any HTML code before th' title head'n. Ye can also set headingPost t' insert HTML code after th' title head'n.

Ye also may want t' apply further CSS 'n 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 ye use th' default layouts/partials/content-footer.html be not overridden by ye, it will display author'n informat'n, namely

See how t' further configure this informat'n 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"
   }
}

Marrrkdown Rules

Let’s face it: Writ'n rrrambl'n fer th' web be tiresome. WYSIWYG editors help alleviate this task, but they generally result 'n horr'ble code, or worse yet, ugly web planks.

Marrrkdown be a better way t' write HTML, without all th' complexities an' ugliness that usually accompanies it.

Some o' th' key benefits be:

  1. Marrrkdown be simple t' learn, wit' minimal extra characters so it’s also quicker t' write rrrambl'n.
  2. Less chance o' errors when writ'n 'n Marrrkdown.
  3. Produces valid HTML output.
  4. Keeps th' rrrambl'n an' th' visual display separate, so ye cannot mess up th' look o' yer ship.
  5. Write 'n any text editor or Marrrkdown applicat'n ye like.
  6. Marrrkdown be a joy t' use!

John Gruber, th' author o' Marrrkdown, puts it like this:

Th' overrid'n design goal fer Markdown’s formatt'n rules be t' make it as read'ble as poss'ble. Th' idea be that a Markdown-formatted document should be publish'ble as-is, as plain text, without look'n like it’s been marked up wit' tags or formatt'n instruct'ns. While Markdown’s rules has been influenced by several exist'n text-to-HTML filters, th' single biggest source o' inspirat'n fer Markdown’s rules be th' format o' plain text email. John Gruber

Smarrrt Arrrse

Bookmark this plank fer easy future reference!

Standard an' Extensions

If not otherwise noted, th' shown examples adhere t' th' CommonMark standard. In addit'n th' theme supports th' follow'n extensions that can be activated 'n yer hugo.toml or be built into th' theme:

Paragraphs

In Marrrkdown yer rrrambl'n usually spans th' whole avail'ble document width. This be called a block. Blocks be always separated by whitespace t' their adjacent blocks 'n th' result'n document.

Any text not start'n wit' a special sign be written as normal, plain text paragraph block an' must be separated t' 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.

Head'ns

A bloody idea be t' structure yer rrrambl'n us'n head'ns an' subhead'ns. HTML-head'ns from h1 through h6 be constructed wit' a # fer each level.

In Hugo ye usually don’t use h1 as this be generated by yer theme an' ye should only have one such element 'n a document.

# h1 Head'n

## h2 Head'n

### h3 Head'n

#### h4 Head'n

##### h5 Head'n

###### h6 Head'n
Result

h1 Head'n

h2 Head'n

h3 Head'n

h4 Head'n

h5 Head'n
h6 Head'n

Horizontal Rules

T' further structure yer rrrambl'n ye can add horizontal rules. They create a “thematic break” between paragraph blocks. In Marrrkdown, ye can create it wit' 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

Quotat'ns

For quot'n blocks o' rrrambl'n from another source within yer document add > before any text ye want t' quote.

Blockquotes can also be nested.

> Donec massa lacus, ultricies a ullamcorper 'n, fermentum sed augue. Nunc augue, aliquam non hendrerit ac, commodo vel nisi.
>
> > Sed adipisc'n elit vitae augue consectetur a gravida nunc vehicula. Donec auctor odio non est accumsan facilisis. Aliquam id turpis 'n 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 'n, fermentum sed augue. Nunc augue, aliquam non hendrerit ac, commodo vel nisi.

Sed adipisc'n elit vitae augue consectetur a gravida nunc vehicula. Donec auctor odio non est accumsan facilisis. Aliquam id turpis 'n 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 Cap'n Hugo 0.132.0 GitHub alerts be also supported. Please note, that color'n an' ay'cons o' severities may defer between GitHub an' this theme.

If ye be 'n need o' more advanced opt'ns t' style yer alerts, like ay'cons, use th' notice shortcode.

> [!CAUTION]
> Advises about risks or negative outcomes o' certain act'ns.

> [!IMPORTANT]
> Key informat'n users need t' know t' achieve their goal.

> [!INFO]
> Informat'n that users <ins>_might_</ins> find interest'n.

> [!NOTE]
> Useful informat'n that users should know, even when skimm'n rrrambl'n.

> [!TIP]
> Helpful advice fer do'n th'ns better or more easily.

> [!WARNING]
> Urgent info that needs immediate user attent'n t' avoid problems.
Result
Caut'n

Advises about risks or negative outcomes o' certain act'ns.

Important

Key informat'n users need t' know t' achieve their goal.

Ahoi

Informat'n that users might find interest'n.

Avast

Useful informat'n that users should know, even when skimm'n rrrambl'n.

Smarrrt Arrrse

Helpful advice fer do'n th'ns better or more easily.

Arrr

Urgent info that needs immediate user attent'n t' avoid problems.

Obsidian Callouts

Obsidian Since Cap'n Hugo 0.134.0 Obsidian callouts be also supported. Which enables configur'ble title text an' expand/collapse.

If ye be 'n need o' more advanced opt'ns t' style yer alerts, like ay'cons, use th' notice shortcode.

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

> [!tip] Title-only callout

> [!note]- Be callouts fold'ble?
> Yes! In a fold'ble callout, th' contents be hidden when th' callout be collapsed

> [!note]+ Be callouts fold'ble?
> Yes! In a fold'ble callout, th' contents be hidden when th' callout be collapsed
Result
Callouts can have custom titles

Like this one.

Title-only callout
Be callouts fold'ble?

Yes! In a fold'ble callout, th' contents be hidden when th' callout be collapsed

Be callouts fold'ble?

Yes! In a fold'ble callout, th' contents be hidden when th' callout be collapsed

Text Markers

Bold

Ye can show importance o' a snippet o' text wit' a heavier font-weight by enclos'n it wit' two asterisks **.

I am rendered wit' **bold text**
Result

I am rendered wit' bold text

Italics

Ye can emphasize a snippet o' text wit' italics by enclos'n it wit' underscores _.

I am rendered wit' _italicized text_
Result

I am rendered wit' italicized text

Marked Text

Ye can mark text 'n th' predefined accent color o' yer stylesheet.

Cap'n Hugo Since Cap'n Hugo 0.126.0, ye can activate this through th' Cap'n Hugo Extra Extension 'n yer hugo.toml

==Parts== o' this text ==are marked!==

HTML Ye can also use it by configur'n Hugo fer usage o' HTML.

<mark>Parts</mark> o' this text <mark>be marked!</mark>
Result

Parts o' this text be marked!

Inserted Text

Ye can mark text addit'ns t' exist'n text.

Cap'n Hugo Since Cap'n Hugo 0.126.0, ye can activate this through th' Cap'n Hugo Extra Extension 'n yer hugo.toml

Th' ++hot, new++ stuff

HTML Ye can also use it by configur'n Hugo fer usage o' HTML.

Th' <ins>hot, new</ins> stuff
Result

Th' hot, new stuff

Deleted Text

GFM Ye can do strikethroughs by enclos'n text wit' two tildes ~~. See Hugo’s documentat'n remarks if ye want t' use this together wit' th' subscript rules.

~~Strike through~~ this text
Result

Strike through this text

Special Typesett'n

Text Substitut'n

Pants Ye can combine multiple punctuat'n characters t' single typographic entities. This will only be applied t' text outside o' code blocks or inline code.

Do'ble quotes `"` an' single quotes `'` o' enclosed text be replaced by **"do'ble curly quotes"** an' **'single curly quotes'**.

Do'ble dashes `--` an' triple dashes `---` be replaced by en-dash **--** an' em-dash **---** entities.

Do'ble arrows point'n left `<<` or right `>>` be replaced by arrow **<<** an' **>>** entities.

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

Do'ble quotes " an' single quotes ' o' enclosed text be replaced by “do'ble curly quotes” an' ‘single curly quotes’.

Do'ble dashes -- an' triple dashes --- be replaced by en-dash – an' em-dash — entities.

Do'ble arrows point'n left << or right >> be replaced by arrow « an' » entities.

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

Subscript an' Superscript

Ye can also use subscript an' superscript text. For more complex stuff, ye can use th' math shortcode.

Cap'n Hugo Since Cap'n Hugo 0.126.0, ye can activate this through th' Cap'n Hugo Extra Extension 'n yer hugo.toml

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

HTML Ye can also use it by configur'n Hugo fer usage o' 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 Ye can use th' <kbd> element t' style keyboard shortcuts.

Press <kbd>STRG</kbd> <kbd>ALT</kbd> <kbd>DEL</kbd> t' end yer shift early.
Result

Press STRG ALT DEL t' end yer shift early.

Lists

Unordered

Ye can write a list o' items 'n which th' order o' th' items does not explicitly matter.

It be poss'ble t' nest lists by indent'n an item fer th' next sublevel.

Ye may use any o' -, * or + t' denote bullets fer each list item but should not switch between those symbols inside one whole list.

- Lorem ipsum dolor sit amet
- Consectetur adipisc'n 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 adipisc'n 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

Ye can create a list o' items 'n which th' order o' items does explicitly matter.

It be poss'ble t' nest lists by indent'n an item fer th' next sublevel.

Marrrkdown will automatically number each o' yer items consecutively. This means, th' order number ye be provid'n be irrelevant.

1. Lorem ipsum dolor sit amet
3. Consectetur adipisc'n elit
    1. Integer molestie lorem at massa
    7. Facilisis 'n 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 adipisc'n elit
    1. Integer molestie lorem at massa
    2. Facilisis 'n 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 Ye can add task lists result'n 'n checked or unchecked non-click'ble items

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

Tree

Relearrrn Ye can add lists as a tree wit' configur'ble ay'cons an' colors.

Th' name can be followed by an optional pipe (|) t' define an ay'con an' further optional pipe t' define th' icon’s color.

More details can be found 'n th' 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

Definit'ns

PHP Definit'n lists be made o' terms an' definit'ns o' these terms, much like 'n a dictionary.

A definit'n list 'n Marrrkdown Extra be made o' a single-line term followed by a colon an' th' definit'n fer that term. Ye can also associate more than one term t' a definit'n.

If ye add empty lines around th' definit'n terms, additional vertical space will be generated. Also multiple paragraphs be poss'ble

Apple
: Pomaceous fruit o' plants o' th' genus Malus 'n th' family Rosaceae.
: An American computer company.

Orange
: Th' fruit o' an evergreen tree o' th' genus Citrus.

  Ye can make juice out o' it.
: A telecommunicat'n company.

  Ye can't make juice out o' it.
Result
Apple
Pomaceous fruit o' plants o' th' genus Malus 'n th' family Rosaceae.
An American computer company.
Orange
Th' fruit o' an evergreen tree o' th' genus Citrus.

Ye can make juice out o' it.

A telecommunicat'n company.

Ye can’t make juice out o' it.

Code

Inline Code

Inline snippets o' code can be wrapped wit' backticks `.

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

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

Indented Code Block

A simple code block can be generated by indent'n several lines o' code by at least two spaces.

Be impressed by my advanced code:

    // Some comments
    line 1 o' code
    line 2 o' code
    line 3 o' code
Result

Be impressed by my advanced code:

// Some comments
line 1 o' code
line 2 o' code
line 3 o' code

Fenced Code Block

If ye want t' gain more control o' yer code block ye can enclose yer code by at least three backticks ``` a so called fence.

GFM Ye can also add a language specifier directly after th' open'n fence, ```js, an' rules highlight'n will automatically be applied accord'n t' th' selected language 'n th' rendered HTML.

See Code Highlight'n fer additional documentat'n.

```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 Ye can create tables by add'n pipes as dividers between each cell, an' by add'n a line o' dashes (also separated by bars) beneath th' header. Avast that th' pipes do not need t' be vertically aligned.

| Opt'n | Descript'n |
|--------|-------------|
| data   | path t' data files t' supply th' data that will be passed into templates. |
| engine | engine t' be used fer process'n templates. Handlebars be th' default. |
| ext    | extension t' be used fer dest files. |
Result
Opt'n Descript'n
data path t' data files t' supply th' data that will be passed into templates.
engine engine t' be used fer process'n templates. Handlebars be th' default.
ext extension t' be used fer dest files.

Aligned Columns

Add'n a colon on th' left and/or right side o' th' dashes below any head'n will align th' text fer that column accordingly.

| Opt'n | Number | Descript'n |
|-------:|:------:|:------------|
| data   | 1      | path t' data files t' supply th' data that will be passed into templates. |
| engine | 2      | engine t' be used fer process'n templates. Handlebars be th' default. |
| ext    | 3      | extension t' be used fer dest files. |
Result
Opt'n Number Descript'n
data 1 path t' data files t' supply th' data that will be passed into templates.
engine 2 engine t' be used fer process'n templates. Handlebars be th' default.
ext 3 extension t' be used fer dest files.

GFM Absolute URLs will automatically be converted into a link.

This be a link t' https://example.com.
Result

This be a link t' https://example.com.

Ye can explicitly define links 'n case ye want t' use non-absolute URLs or want t' give different text.

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

Assemble

For even further informat'n, ye can add an additional text, displayed 'n a tooltip on hover'n over th' link.

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

Upstage

Links can be simplyfied fer recurr'n reuse by us'n a reference ID t' later define th' URL locat'n. This simplyfies writ'n if ye want t' use a link more than once 'n a document.

[Example][somelinkID]

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

Example

Footnotes

PHP Footnotes work mostly like reference-style links. A footnote be made o' two th'ns, a marker 'n th' text that will become a superscript number an' a footnote definit'n that will be placed 'n a list o' footnotes.

Usually th' list o' footnotes will be shown at th' end o' yer document. If we use a footnote 'n a notice box it will instead be listed at th' end o' its box.

Footnotes can contain block elements, which means that ye can put multiple paragraphs, lists, blockquotes an' so on 'n a footnote. It works th' same as fer list items, just indent th' follow'n paragraphs by four spaces 'n th' footnote definit'n.

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

[^1]: An' that's th' footnote.

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

[^someid]:
    Anyth'n o' interest goes here.

    Blue light glows blue.
Result

That’s some text wit' a footnote1

That’s some more text wit' a footnote.2

  1. An' that’s th' footnote. ↩︎

  2. Anyth'n o' interest goes here.

    Blue light glows blue. ↩︎

Relearrrn This theme allows additional non-standard formatt'n by sett'n query parameter at th' end o' th' URL. See th' link effects docs fer a detailed example an' how t' configure it.

Target

Add query parameter target=_self or target=_blank t' override site-wide sett'ns o' th' target behavior individuallly fer each link.

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

Magic 'n new window

Download

Add query parameter download or download=myfile.gif t' force yer browser t' download th' link target instead o' open'n it.

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

Magic as a download

Images

Basic Images

Images have a similar rules t' links but include a preced'n exclamat'n mark.

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

Spock Spock

Image wit' 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 t' later define th' URL locat'n. This simplyfies writ'n if ye want t' use an image more than once 'n a document.

![La Forge][laforge]

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

La Forge La Forge

Image Effects

Relearrrn This theme allows additional non-standard formatt'n by sett'n query parameter at th' end o' th' image URL. See th' image effects docs fer a detailed example an' how t' configure it.

Resiz'n

Add query parameter width and/or height t' th' link image t' resize th' image. Values be CSS values (default be 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 t' th' link image t' add CSS classes. Add some o' th' predefined values or even define yer own 'n yer 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

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

X-tocat X-tocat

Add th' query parameter lightbox=false t' th' image link t' dis'ble th' lightbox.

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

Homercat

Avast

If ye want t' wrap an image 'n a link an' lightbox=true be yer default sett'n, ye have t' explicitly dis'ble th' lightbox t' avoid it t' hijack'n yer link like:

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

Homercat

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.