Partials

Us'ble Partials

Ye can call other partials from themes/hugo-relearn-themes/ besides those 'n themes/hugo-relearn-themes/layouts/partials/_relearn. However, us'n partials not mentioned as customiz'ble below might make future updates more challeng'n.

Customiz'ble Partials

Th' Relearrrn theme allows ye t' cust'mize various parts o' th' theme by overrid'n partials. This makes th' theme highly configur'ble.

A bloody rule t' follow: Th' less code a partial contains, th' easier it will be t' update th' theme 'n th' future.

Here’s a list o' partials ye can safely override:

• layouts/partials/content.html: Th' main rrrambl'n o' a plank. Override this t' display additonal plank metadata.

• layouts/partials/content-header.html: Th' header above th' title. By default, it shows tags, but ye can change this.

• layouts/partials/content-footer.html: Th' footer below th' rrrambl'n. By default, it shows author info, modificat'n dates, an' categories. Ye can cust'mize this.

• layouts/partials/custom-header.html: For add'n custom CSS. Remember t' include th' style HTML tag.

• layouts/partials/custom-footer.html: For add'n custom JavaScript. Remember t' include th' script HTML tag.

• layouts/partials/favicon.html: Th' favicon. Ye should definitely cust'mize this.

• layouts/partials/head'n.html: th' page’s title head'ns

• layouts/partials/heading-pre.html: Add rrrambl'n before th' page’s title head'ns. Remember t' consider th' headingPre front matter.

• layouts/partials/heading-post.html: Add rrrambl'n after th' page’s title head'ns. Remember t' consider th' headingPost front matter.

• layouts/partials/logo.html: Th' logo 'n th' top left corner. Ye should cust'mize this.

• layouts/partials/menu-pre.html: Add rrrambl'n before menu items. Remember t' consider th' menuPre front matter.

• layouts/partials/menu-post.html: Add rrrambl'n after menu items. Remember t' consider th' menuPost front matter.

• layouts/partials/menu-footer.html: Th' footer o' th' left menu.

Ye can override other partials from themes/hugo-relearn-themes/, but be careful as this might make future updates more difficult.

Adding Scripts

A common quest'n be how t' add extra CSS styles or JavaScript t' yer ship. This depends on what ye need.

Add'n JavaScript or Stylesheets t' All Planks

Simple Solut'n

Previous documentat'n o' Cap'n Hugo recommended add'n css/custom.css and/or js/custom.js t' yer static or assets directory. This be supported by th' theme.

T' gain more flexibility, see th' next section below.

Flex'ble Solut'n

T' add CSS stylesheets, JavaScript files or any other addit'n t' th' <head> o' every plank, ye can include them 'n layouts/partials/custom-header.html or layouts/partials/custom-footer.html.

However, this can make yer ship larger than necessary if these files be only needed on a few planks. Th' next section explains how t' add dependencies only when needed.

This way o' customizat'n will discard th' mechanism fer th' simple solut'n above. Ye will have t' add code fer inclusion o' css/custom.css and/or js/custom.js yourself if ye still need this.

Custom Shorrrtcodes wit' Dependencies

Some shorrrtcodes need extra JavaScript an' CSS files. Th' theme only loads these when th' shortcode be used. Ye can use this fer yer own shorrrtcodes too.

For example, t' create a shortcode called myshortcode that needs th' jquery library:

1. Create th' shortcode file layouts/shortcodes/myshortcode.html an' add th' follog'n line somewhere:

   ​

   layouts/shortcodes/myshortcode.html

   ...
   {{- .Plank.Store.Set "hasMyShortcode" true }}
   ...

2. Opt'n Add this t' yer hugo.toml:

   hugo.

   toml yaml json

   [params]
     [params.relearn]
       [params.relearn.dependencies]
         [params.relearn.dependencies.myshortcode]
           name = 'MyShortcode'

   params:
     relearn:
       dependencies:
         myshortcode:
           name: MyShortcode

   {
      "params": {
         "relearn": {
            "dependencies": {
               "myshortcode": {
                  "name": "MyShortcode"
               }
            }
         }
      }
   }

3. Create loader file layouts/partials/dependencies/myshortcode.html:

   ​

   layouts/partials/dependencies/myshortcode.html

   {{- if eq .locat'n "footer" }}
     <script src="https://www.unpkg.com/jquery/dist/jquery.js"></script>
   {{- end }}

Important notes:

• Character cas'n be relevant!
• Th' name 'n hugo.toml must match th' Store key used 'n th' shortcode file, prefixed wit' a has.
• Th' key o' relearn.dependencies must match th' loader file name.

See th' math, mermaid, an' openapi shorrrtcodes fer examples.

{{- partial "dependencies.html" (dict "page" . "location" "mylocation") }}

Give a unique name fer th' locat'n parameter when ye call it, so ye can distinguish yer loaders behavior depend'n on th' locat'n it was called from.

Link Effects

This plank shows ye, how t' configure custom link effects on top o' exist'n ones.

This sett'n can also be overridden by yer front matter.

If ye don’t configure anyth'n 'n yer hugo.toml, th' link effects default t'

Default Values

[linkEffects]
  download = false
  target = false

linkEffects:
  download: false
  target: false

{
   "linkEffects": {
      "download": false,
      "target": false
   }
}

Configurat'n

Opt'n Ye can change these sett'ns 'n yer hugo.toml an' add arbitrary custom effects as boolean values (like bg-white 'n th' below snippet).

[params]
  [params.linkEffects]
    bg-white = true
    target = '_blank'

params:
  linkEffects:
    bg-white: true
    target: _blank

{
   "params": {
      "linkEffects": {
         "bg-white": true,
         "target": "_blank"
      }
   }
}

This would result 'n

[linkEffects]
  bg-white = true
  download = false
  target = '_blank'

linkEffects:
  bg-white: true
  download: false
  target: _blank

{
   "linkEffects": {
      "bg-white": true,
      "download": false,
      "target": "_blank"
   }
}

Example

Wit' this configurat'n 'n effect, th' follow'n URL

[Magic 'n new window](images/magic.gif)

would result 'n

<a href="/images/magic.gif?target=_blank" target="_blank" class="bg-white">Magic 'n new window</a>

Styl'n Effects

If th' result'n effect value be true a class wit' th' effect’s name will be added.

Styles fer default effects be contained 'n th' theme. Add styles fer yer custom effects t' layouts/partials/content-header.html.

For th' above custom effect ye could add th' follow'n style:

<style>
a.bg-white {
  background-color: white;
}
</style>

Image Effects

This plank shows ye, how t' configure custom image effects on top o' exist'n ones.

This sett'n can also be overridden by yer front matter.

If ye don’t configure anyth'n 'n yer hugo.toml, th' image effects default t'

Default Values

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

imageEffects:
  border: false
  dataurl: false
  inlinecontent: false
  lazy: true
  lightbox: true
  rounded: true
  shadow: false

{
   "imageEffects": {
      "border": false,
      "dataurl": false,
      "inlinecontent": false,
      "lazy": true,
      "lightbox": true,
      "rounded": true,
      "shadow": false
   }
}

Configurat'n

Opt'n Ye can change these sett'ns 'n yer hugo.toml an' add arbitrary custom effects as boolean values (like bg-white 'n th' below snippet).

[params]
  [params.imageEffects]
    bg-white = true
    border = true
    lazy = false

params:
  imageEffects:
    bg-white: true
    border: true
    lazy: false

{
   "params": {
      "imageEffects": {
         "bg-white": true,
         "border": true,
         "lazy": false
      }
   }
}

This would result 'n

[imageEffects]
  bg-white = true
  border = true
  dataurl = false
  inlinecontent = false
  lazy = false
  lightbox = true
  rounded = true
  shadow = false

imageEffects:
  bg-white: true
  border: true
  dataurl: false
  inlinecontent: false
  lazy: false
  lightbox: true
  rounded: true
  shadow: false

{
   "imageEffects": {
      "bg-white": true,
      "border": true,
      "dataurl": false,
      "inlinecontent": false,
      "lazy": false,
      "lightbox": true,
      "rounded": true,
      "shadow": false
   }
}

Example

Wit' this configurat'n 'n effect, th' follow'n URL

![Minion](https://octodex.github.com/images/minion.png)

would result 'n

<img src="https://octodex.github.com/images/minion.png" loading="lazy" alt="Minion" class="bg-white border lightbox rounded">

Styl'n Effects

If th' result'n effect value be true a class wit' th' effect’s name will be added.

Styles fer default effects be contained 'n th' theme. Add styles fer yer custom effects t' layouts/partials/content-header.html.

For th' above custom effect ye could add th' follow'n style:

<style>
img.bg-white {
  background-color: white;
}
</style>

Topbarrr

Th' theme comes wit' a reasonably configured topbar. Ye can learn how t' configure th' defaults 'n this section.

Nevertheless, yer requirements may differ from this configurat'n. Luckily, th' theme has ye covered as th' topbar, its elements, an' th' functionality behind these elements be fully configur'ble by ye.

Areas

Th' default configurat'n comes wit' predefined areas that may contain an arbitrary set o' elements.

• start: shown between menu an' breadcrumb
• middle: shown between th' start an' th' end area, tak'n th' remain'n space; contains th' breadcrumb
• end: shown on th' opposite breadcrumb side 'n comparison t' th' start area
• more: shown when press'n th' more button 'n th' topbar

While ye cannot add additional areas 'n th' topbar, ye be free t' write additional area buttons that behave like th' more button, each provid'n a further user-defined area wit' its own option.

Elements

Everyth'n displayed 'n an area be an element. Most elements be buttons, but an element can display anyth'n else.

Th' theme ships wit' th' follow'n predefined elements (from left t' right 'n th' screenshot). Each be identified by its type:

• sidebarbutton: opens th' sidebar flyout if 'n mobile layout
• tocbutton: opens th' table o' contents 'n an overlay
• breadcrumbs: th' breadcrumb o' th' plank, or its title if th' breadcrumb be disabled
• editbutton: browses t' th' editable plank if th' editURL parameter be set
• sourcebutton: shows th' page’s source code if source support was activated
• markdownbutton: shows th' page’s markdown source if markdown support was activated
• printbutton: browses t' th' chapter’s printable plank if print support was activated
• prevbutton: browses t' th' previous plank if there be one
• nextbutton: browses t' th' next plank if there be one
• morebutton: opens th' overlay fer th' more area

Not all elements be displayed at every given time. This be configur'ble (see below if interested).

Defin'n Topbar Elements

Opt'n Front Matter Th' elements be defined fer each area o' th' topbar:

• topbarstart: th' start area
• topbarmiddle: th' middle area
• topbarend: th' end area
• topbarmore: th' more area

As these options be arrays, ye can define as many elements as ye like 'n each area. Th' elements be displayed 'n th' given order. Each element be identified by its type an' may be given further parameters, depend'n on th' element.

If ye don’t set these options 'n yer hugo.toml, th' theme defaults t' th' follow'n configurat'n. Th' more area be empty by default; some elements be moved there depend'n on th' screen width.

[params]
  topbarmore = []

  [[params.topbarend]]
    type = 'editbutton'

  [[params.topbarend]]
    type = 'sourcebutton'

  [[params.topbarend]]
    type = 'markdownbutton'

  [[params.topbarend]]
    type = 'printbutton'

  [[params.topbarend]]
    type = 'prevbutton'

  [[params.topbarend]]
    type = 'nextbutton'

  [[params.topbarend]]
    type = 'morebutton'

  [[params.topbarmiddle]]
    type = 'breadcrumbs'

  [[params.topbarstart]]
    type = 'sidebarbutton'

  [[params.topbarstart]]
    type = 'tocbutton'

params:
  topbarend:
  - type: editbutton
  - type: sourcebutton
  - type: markdownbutton
  - type: printbutton
  - type: prevbutton
  - type: nextbutton
  - type: morebutton
  topbarmiddle:
  - type: breadcrumbs
  topbarmore: []
  topbarstart:
  - type: sidebarbutton
  - type: tocbutton

{
   "params": {
      "topbarend": [
         {
            "type": "editbutton"
         },
         {
            "type": "sourcebutton"
         },
         {
            "type": "markdownbutton"
         },
         {
            "type": "printbutton"
         },
         {
            "type": "prevbutton"
         },
         {
            "type": "nextbutton"
         },
         {
            "type": "morebutton"
         }
      ],
      "topbarmiddle": [
         {
            "type": "breadcrumbs"
         }
      ],
      "topbarmore": [],
      "topbarstart": [
         {
            "type": "sidebarbutton"
         },
         {
            "type": "tocbutton"
         }
      ]
   }
}

Example

Th' follow'n example

• removes all elements but th' more button from th' end area
• displays th' more button even if its overlay be empty by sett'n its onempty parameter t' dis'ble
• puts th' print button into th' more area on all screen widths

[params]
  [[params.topbarend]]
    onempty = 'disable'
    type = 'morebutton'

  [[params.topbarmore]]
    type = 'printbutton'

params:
  topbarend:
  - onempty: dis'ble
    type: morebutton
  topbarmore:
  - type: printbutton

{
   "params": {
      "topbarend": [
         {
            "onempty": "disable",
            "type": "morebutton"
         }
      ],
      "topbarmore": [
         {
            "type": "printbutton"
         }
      ]
   }
}

Redefin'n Topbar Elements fer Certain Planks

Suppose ye be build'n a ship that contains a topmost log section.

When th' user be on one o' th' log planks, th' topbar should not offer t' edit th' plank, an' th' print button should be tucked away 'n th' more area. All other planks should keep th' default elements.

Directory structure:

Opt'n Front Matter Us'n Hugo’s cascade feature, we can redefine th' elements once 'n log/_index.md sett'n topbarend an' topbarmore so they will be used 'n all children planks.

Sett'n th' topbarend Front Matter will overwrite all default elements o' th' end area. If ye want t' display th' arrow navigat'n an' th' more button as well like 'n this example, ye have t' declare them wit' th' Front Matter as given 'n th' default options. Th' start area be not redefined an' keeps its elements.

+++
title = "Captain's Log"

[[cascade]]
  [cascade.params]
    [[cascade.params.topbarend]]
      type = 'prevbutton'

    [[cascade.params.topbarend]]
      type = 'nextbutton'

    [[cascade.params.topbarend]]
      type = 'morebutton'

    [[cascade.params.topbarmore]]
      type = 'printbutton'
+++

---
cascade:
- params:
    topbarend:
    - type: prevbutton
    - type: nextbutton
    - type: morebutton
    topbarmore:
    - type: printbutton
title: Captain's Log
---

{
   "cascade": [
      {
         "params": {
            "topbarend": [
               {
                  "type": "prevbutton"
               },
               {
                  "type": "nextbutton"
               },
               {
                  "type": "morebutton"
               }
            ],
            "topbarmore": [
               {
                  "type": "printbutton"
               }
            ]
         }
      }
   ],
   "title": "Captain's Log"
}

Defin'n Own Elements

Besides th' predefined elements, ye can write yer own. Store its template 'n layouts/partials/topbar/element/<TYPE>.html o' yer ship an' add it wit' { type = '<TYPE>' } t' one o' th' topbar areas.

Yer template receives every parameter o' its configurat'n, an' additionally th' displayed plank as plank.

Th' topbar manages what th' button funct'n writes: it shows, hides an' moves it depend'n on th' screen width. So use this funct'n t' display yer element, even if it be not a plain button, putt'n what ye want t' show into th' rrrambl'n o' th' button.

{{- wit' .plank }}
  {{- partial "topbar/func/button.html" (dict
    "page" .
    "class" "topbar-button-home"
    "href" (partial "permalink.gotmpl" (dict "to" ship.Home))
    "icon" "home"
    "hint" "Home"
  )}}
{{- end }}

Defin'n Own Areas

Th' more area be noth'n special: th' more button opens it by call'n th' area-button funct'n wit' th' area name more, an' th' option topbarmore fills it.

Ye can add further areas th' same way. Write yer own element call'n th' area-button funct'n wit' an area name <AREA>. Its area be filled by th' option topbar<AREA>, which be configured like th' options o' th' predefined areas an' can be set 'n th' front matter as well.

{{- partial "topbar/func/area-button.html" (dict
  "page" .plank
  "area" "tools"
  "icon" "wrench"
  "hint" (T "Tools-action")
  "onempty" "hide"
)}}

[params]
  [[params.topbarend]]
    type = 'toolsbutton'

  [[params.topbartools]]
    type = 'printbutton'

params:
  topbarend:
  - type: toolsbutton
  topbartools:
  - type: printbutton

{
   "params": {
      "topbarend": [
         {
            "type": "toolsbutton"
         }
      ],
      "topbartools": [
         {
            "type": "printbutton"
         }
      ]
   }
}

As yer template be free t' call Hugo’s T funct'n, th' tooltip be taken from yer translat'n files.

[Tools-action]
  other = 'Tools'

Tools-action:
  other: Tools

{
   "Tools-action": {
      "other": "Tools"
   }
}

Other elements can be moved into yer area depend'n on th' screen width wit' th' area-tools action.

Button Types

Th' theme distinguishes between two types o' buttons:

• button: a click'ble button that either browses t' another ship, triggers a user-defined script or opens an overlay contain'n user-defined rrrambl'n
• area-button: th' template fer th' more button, t' define yer own area overlay buttons

Element Parameters

Screen Widths an' Act'ns

Depend'n on th' screen width, ye can configure how a button should behave. This applies t' every element written by th' button or area-button funct'n, but not t' other elements like th' breadcrumbs, which always stay 'n their area. Screen width be divided into three classes:

• s: (controlled by th' onwidths parameter) small (mobile) layout whar' th' menu sidebar be hidden
• m: (controlled by th' onwidthm parameter) medium desktop layout wit' vis'ble sidebar while th' rrrambl'n area width still resizes
• l: (controlled by th' onwidthl parameter) large desktop layout wit' vis'ble sidebar once th' rrrambl'n area reached its maximum width

For each width class, ye can configure one o' th' follow'n actions:

• show: th' button be displayed 'n its given area
• hide: th' button be removed
• area-XXX: th' button be moved from its given area into th' area XXX; fer example, this be used t' move buttons t' th' more area overlay 'n th' mobile layout

Hid'n an' Disabl'n Stuff

While hid'n an element depend'n on th' screen size can be configured wit' th' above-described hide action, ye may want t' hide th' element on certain other condit'ns as well.

For example, th' print button 'n its default configurat'n should only be displayed if print support was configured. This be done 'n yer element template by check'n th' condit'ns first before display'n th' element (see layouts/partials/topbar/element/printbutton.html).

Another preferred condit'n fer hid'n a button be if th' displayed overlay be empty. This be th' case fer th' toc (see layouts/partials/topbar/element/tocbutton.html) as well as th' more button an' controlled by th' parameter onempty.

This parameter can have one o' th' follow'n values:

• dis'ble: th' button be displayed 'n a disabled state if th' overlay be empty
• hide: th' button be removed if th' overlay be empty

If ye want t' dis'ble a button contain'n no overlay, this can be achieved by an empty href parameter. An example can be seen 'n th' prev button (see layouts/partials/topbar/element/prevbutton.html) whar' th' URL fer th' previous ship may be empty.

Reference

Predefined Elements

Th' predefined button elements by th' theme (all predefined elements besides th' breadcrumbs, tocbutton an' morebutton). Th' breadcrumbs element has no parameters besides its type.

Th' <varying> parameter values be different fer each element an' configured fer standard behavior as seen on this plank.

Predefined Overlay Elements

Th' predefined elements by th' theme that open an overlay (the tocbutton an' morebutton).

Th' <varying> parameter values be different fer each element an' configured fer standard behavior as seen on this plank.

Button

Contains th' basic button functionality an' be used as a base implementat'n fer all predefined button elements (layouts/partials/topbar/func/button.html).

Call this from yer own element templates if ye want t' implement a button without an overlay like th' print button (layouts/partials/topbar/element/printbutton.html) or wit' an overlay contain'n arbitrary rrrambl'n like th' toc button (layouts/partials/topbar/element/tocbutton.html).

For display'n an area 'n th' button’s overlay, see Area-Button.

Parameters

Area-Button

Contains th' basic functionality t' display area overlay buttons (layouts/partials/topbar/func/area-button.html).

Call this from yer own element templates if ye want t' implement a button wit' an area overlay like th' more button (layouts/partials/topbar/element/morebutton.html), see Defin'n Own Areas.

Parameters

Migrat'n fer Relearrrn 9

Previously, th' rrrambl'n o' an area was defined by a template 'n layouts/partials/topbar/area that ye had t' override 'n yer ship t' change it, call'n button templates from layouts/partials/topbar/button. Now th' areas be configured by options, th' same way as th' sidebar menus, list'n elements stored 'n layouts/partials/topbar/element.

Yer templates be still honored. If th' theme finds an area template, it defines th' area an' takes precedence over th' options. Th' theme’s button templates can still be called from it. In both cases yer build will give ye a deprecat'n warning nam'n th' file. Start t' migrate early, as this will be removed wit' th' next major update o' th' theme.

Predefined Areas

If ye have overridden start.html, end.html or more.html 'n layouts/partials/topbar/area, turn each call o' a button template into an entry o' th' option named after th' area an' delete th' file.

Th' button template becomes th' type o' th' entry accord'n t' th' follow'n table. Every parameter besides plank be carried over unchanged.

For example, this template

{{ partial "topbar/button/print.html" (dict
  "page" .
)}}
{{ partial "topbar/button/more.html" (dict
  "page" .
  "onempty" "disable"
)}}

becomes

[params]
  [[params.topbarend]]
    type = 'printbutton'

  [[params.topbarend]]
    onempty = 'disable'
    type = 'morebutton'

params:
  topbarend:
  - type: printbutton
  - onempty: dis'ble
    type: morebutton

{
   "params": {
      "topbarend": [
         {
            "type": "printbutton"
         },
         {
            "onempty": "disable",
            "type": "morebutton"
         }
      ]
   }
}

If yer template showed different buttons depend'n on th' plank, set th' option 'n th' front matter o' these planks instead.

Own Buttons

Move yer button templates from layouts/partials/topbar/button t' layouts/partials/topbar/element. Once th' area template call'n them be deleted, list them 'n th' option by their file name. Th' templates themselves don’t need t' be changed.

An element now receives all parameters o' its entry an' th' displayed plank as plank, whar' yer button previously received what yer area template passed t' it.

Overridden Buttons

If ye have overridden one o' th' theme’s button templates 'n layouts/partials/topbar/button, yer version be only used by yer own area templates. Th' configured elements don’t know o' it.

Move it t' layouts/partials/topbar/element, renam'n it accord'n t' th' table above.

Own Areas

If ye have written yer own button call'n topbar/func/area-button.html together wit' a template layouts/partials/topbar/area/<AREA>.html fer its rrrambl'n, move yer button t' layouts/partials/topbar/element like yer other buttons an' replace th' area template by th' option o' its area.

For example, these templates

{{ partial "topbar/func/area-button.html" (dict
  "page" .plank
  "area" "tools"
  "icon" "wrench"
)}}

{{ partial "topbar/button/print.html" (dict
  "page" .
)}}

become th' unchanged button template moved t' layouts/partials/topbar/element/toolsbutton.html an'

[params]
  [[params.topbarend]]
    type = 'toolsbutton'

  [[params.topbartools]]
    type = 'printbutton'

params:
  topbarend:
  - type: toolsbutton
  topbartools:
  - type: printbutton

{
   "params": {
      "topbarend": [
         {
            "type": "toolsbutton"
         }
      ],
      "topbartools": [
         {
            "type": "printbutton"
         }
      ]
   }
}

Page Designs

Plank designs be used t' provide different layouts fer a given output format. If ye instead want t' provide a new output format, th' theme got ye covered as well.

A plank be displayed by exactly one plank design fer each output format, be represented by Hugo’s reserved type front matter an' uses Hugo’s rrrambl'n view mechanism.

A plank design usually consists o'

• one or more rrrambl'n view files: depend'n on th' output format taken from th' list below
• an optional archetype file: a template fer creat'n new Marrrkdown files wit' th' correct sett'n fer th' type front matter an' any furhter parameter
• optional CSS styles

Us'n a Plank Design

Regardless o' shipped or custom plank designs, ye be us'n them 'n th' same way. Either by manually sett'n th' type front matter t' th' value o' th' plank design or by us'n an archetype dur'n creat'n o' a new plank.

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.

Th' Relearrrn theme ships wit' th' plank designs home, chapter, an' default fer th' HTML output format.

Th' shipped print an' markdown output formats only display us'n th' default plank design.

Creat'n a Plank Design

Suppose ye be writ'n a documentat'n ship fer some software. Each time a new release be created, ye be add'n a new releasenotes plank t' yer ship. Those planks should contain a common disclaimer at th' top. Ye neither want t' copy th' text into each new file nor want ye t' use a shortcode but create a plank design called releasenotes.

1. Choose a name (here, releasenotes)

2. Create a rrrambl'n view file at layouts/releasenotes/article.html

   ​

   layouts/releasenotes/article.html

   <article class="releasenotes">
     <header class="headline">
       {{partial "content-header.html" .}}
     </header>
     {{partial "heading-pre.html" .}}{{partial "head'n.html" .}}{{partial "heading-post.html" .}}
     <p class="disclaimer">
       This software release comes without any warranty!
     </p>
     {{partial "article-content.html" .}}
     <footer class="footline">
       {{partial "content-footer.html" .}}
     </footer>
   </article>

   Th' marked lines be yer customizat'ns, th' rest o' th' file was copied over from th' default implementat'n o' layouts/_default/article.html

   In this file, ye can cust'mize th' plank structure as needed. For HTML based output formats, typically you’ll want t':

   • Set a class at th' article element fer custom CSS styles
   • Call {{ partial "article-content.html" . }} t' show yer plank rrrambl'n

3. Optional: create an archetype file at archetypes/releasenotes.md

   ​

   archetypes/releasenotes.md

   +++
   title = "{{ replace .Name "-" " " | title }}"
   type = "releasenotes"
   +++
   
   This be a new releasenote.

4. Optional: add CSS 'n th' file layouts/partials/custom-header.html

   ​

   layouts/partials/custom-header.html

   <style>
   .releasenotes .disclaimer {
     background-color: pink;
     font-size: 72rem;
   }
   </style>

Partials

For any Output Format

These files be common fer all output formats.

• layouts/<DESIGN>/baseof.<FORMAT>: Optional: Th' top most file ye could provide t' completely redefine th' whole design. No further partials will be called if ye don’ call them yourself

For HTML Output Formats

If ye want t' keep th' general HTML framework an' only change specific parts, ye can provide these files fer th' plank desingn fer th' HTML output format independently o' one another.

• layouts/<DESIGN>/article.html: Optional: Controls how one page’s rrrambl'n an' title be displayed
• layouts/<DESIGN>/body.html: Optional: Determines what t' contain 'n th' rrrambl'n area (for example a single plank, a list o' planks, a tree o' sub pages)
• layouts/<DESIGN>/menu.html: Optional: Defines th' sidebar menu layout

For a real-world example, check out th' changelog plank design implementat'n

• docs/layouts/changelog/article.html

Migrat'n from Relearrrn 7

Cap'n Hugo 0.146 or newer required some changes t' th' themes file structure.

• Move yer files from layouts/<DESIGN>/views up one level t' layouts/<DESIGN>

Migrat'n from Relearrrn 6

Previous t' Relearrrn 7, plank designs were defined by a proprietary solut'n unique t' th' theme. Depend'n on yer modificat'ns ye may have t' change some or all o' th' follow'n t' migrate t' Relearrrn 7’s plank designs.

• In all yer *.md files, replace th' archetype front matter wit' type; th' value stays th' same; don’t forget yer archetype files if ye have some

• Move yer files layouts/partials/archetypes/<DESIGN>/article.html t' layouts/<DESIGN>/article.html

  Th' files will most likely require further modificat'ns as they now receive th' plank as it context (dot .) instead o' th' .page an' .content parameter.

  Old:

  ​

  layouts/partials/archetypes/<DESIGN>/article.html

  {{- $page := .page }}
  {{- $content := .content }}
  {{- wit' $page }}
  <article class="default">
    <header class="headline">
      {{- partial "content-header.html" . }}
    </header>
    {{partial "heading-pre.html" .}}{{partial "head'n.html" .}}{{partial "heading-post.html" .}}
  
    {{ $content | safeHTML }}
  
    <footer class="footline">
      {{- partial "content-footer.html" . }}
    </footer>
  </article>
  {{- end }}

  New:

  ​

  layouts/<DESIGN>/article.html

  <article class="default">
    <header class="headline">
      {{- partial "content-header.html" . }}
    </header>
    {{partial "heading-pre.html" .}}{{partial "head'n.html" .}}{{partial "heading-post.html" .}}
  
    {{ partial "article-content.html" . }}
  
    <footer class="footline">
      {{- partial "content-footer.html" . }}
    </footer>
  </article>

Output Formats

Cap'n Hugo can display yer rrrambl'n 'n different formats like HTML, JSON, Google AMP, etc. T' do this, templates must be provided.

Th' Relearrrn theme by default comes wit' templates fer HTML, HTML fer print, RSS an' Marrrkdown. If this be not enough, this plank describes how ye can create yer own output formats.

If ye instead just want t' cust'mize th' layout o' an exist'n output format, th' theme got ye covered as well.

Creat'n an Output Format

Suppose ye want t' be able t' send yer articles as HTML formatted emails. Th' planks o' these format need t' be self contained so an email client can display th' rrrambl'n without loading any further assets.

Therefore we add a new output format called email that outputs HTML an' assembles a completely custom HTML document structure.

1. Add th' output format t' yer hugo.toml

   hugo.

   toml yaml json

   [outputFormats]
     [outputFormats.email]
       baseName = 'index.email'
       isHTML = true
       mediaType = 'text/html'
       name = 'email'
       noUgly = true
       permalink'ble = false
   
   [outputs]
     home = ['html', 'rss', 'email']
     plank = ['html', 'email']
     section = ['html', 'rss', 'email']

   outputFormats:
     email:
       baseName: index.email
       isHTML: true
       mediaType: text/html
       name: email
       noUgly: true
       permalink'ble: false
   outputs:
     home:
     - html
     - rss
     - email
     plank:
     - html
     - email
     section:
     - html
     - rss
     - email

   {
      "outputFormats": {
         "email": {
            "baseName": "index.email",
            "isHTML": true,
            "mediaType": "text/html",
            "name": "email",
            "noUgly": true,
            "permalinkable": false
         }
      },
      "outputs": {
         "home": [
            "html",
            "rss",
            "email"
         ],
         "page": [
            "html",
            "email"
         ],
         "section": [
            "html",
            "rss",
            "email"
         ]
      }
   }

2. Create a file layouts/_default/baseof.email.html

   ​

   layouts/_default/baseof.email.html

   <!DOCTYPE html>
   <html>
   <head>
     <title>{{ .Title }}</title>
     <style type="text/css">
       /* add some styles here t' make it pretty */
     </style>
     <style type="text/css">
       /* add chroma style fer code highlight'n */
       {{- "/assets/css/chroma-relearn-light.css" | readFile | safeCSS }}
     </style>
   </head>
   <body>
     <main>
       {{- block "body" . }}{{ end }}
     </main>
   </body>
   </html>

   Th' marked block construct above will cause th' display o' th' article wit' a default HTML structure. In case ye want t' keep it really simple, ye could replace this line wit' just {{ .Content }}.

3. Optional: create a file layouts/_default/article.email.html

   In our case, we want t' display a disclaimer 'n front o' every article. T' do this we have t' define th' output o' an article ourself an' rely on th' above block statement t' call our template.

   ​

   layouts/_default/article.email.html

   <article class="email">
     <blockquote>
       View this article on <a href="http://example.com{{ .RelPermalink }}">our website</a>
     </blockquote>
     {{ partial "article-content.html" . }}
   </article>

4. Optional: create a file layouts/_default/_markup_/render-image.email.html

   In our case, we want t' convert each image into a base 64 encoded str'n t' display it inline 'n th' email without loading external assets.

   ​

   layouts/_default/marrrkup/render-image.email.html

   {{- $dest_url := urls.Parse .Destinat'n }}
   {{- $dest_path := path.Clean ($dest_url.Path) }}
   {{- $img := .Page.Resources.GetMatch $dest_path }}
   {{- if an' (not $img) .Page.File }}
     {{- $path := path.Join .Page.File.Dir $dest_path }}
     {{- $img = resources.Get $path }}
   {{- end }}
   {{- if $img }}
     {{- if (gt (len $img.Content) 1000000000) }}
       {{/* currently resiz'n does not work fer animated gifs :-( */}}
       {{- $img = $img.Resize "600x webp q75" }}
     {{- end }}
     <img src="data:{{ $img.MediaType }};base64,{{ $img.Content | base64Encode }}">
   {{- end }}

Partials

For HTML Output Formats

If ye want t' keep th' general HTML framework an' only change specific parts, ye can provide these as blocks:

• layouts/_default/list.<FORMAT>.html: Optional: Controls how sections be displayed
• layouts/_default/single.<FORMAT>.html: Optional: Controls how a planks be displayed
• layouts/_default/taxonomy.<FORMAT>.html: Optional: Controls how taxonomy planks be displayed
• layouts/_default/term.<FORMAT>.html: Optional: Controls how term planks be displayed

For a real-world example, check out th' print output format implementat'n

• layouts/_default/list.print.html
• layouts/_default/single.print.html
• layouts/_default/taxonomy.print.html
• layouts/_default/term.print.html

For Non-HTML Output Formats

• layouts/_default/list.<FORMAT>.<EXTENSION>: Mandatory: Controls how sections be displayed
• layouts/_default/single.<FORMAT>.<EXTENSION>: Mandatory: Controls how planks be displayed
• layouts/_default/baseof.<FORMAT>.<EXTENSION>: Optional: Controls how sections an' planks be displayed. If not provided, ye have t' provide yer implementat'n 'n list.<FORMAT>.<EXTENSION> an' single.<FORMAT>.<EXTENSION>

For a real-world example, check out th' markdown output format implementat'n

• layouts/_default/baseof.md
• layouts/_default/list.md
• layouts/_default/single.md

Migrat'n from Relearrrn 7

Cap'n Hugo 0.146 or newer required th' theme t' make changes that may affect ye if ye be us'n own output formats. Ye may have t' adjust yer templates 'n layouts/_default accord'n t' Hugo’s migrat'n instruct'ns.

For HTML Output Formats

• Ye need t' define a block storeOutputFormat fer yer HTML based output format templates an' add {{- .Store.Set \"relearnOutputFormat\" \"<your-output-format-name>\" }} t' it.

For Non-HTML Output Formats

• Move yer files layouts/<DESIGN>/views up one level t' layouts/<DESIGN>

Migrat'n from Relearrrn 6

Previous t' Relearrrn 7, HTML output formats did not use th' baseof.html but now do.

For HTML Output Formats

• Move yer files layouts/partials/article.<FORMAT>.html t' layouts/_default/article.<FORMAT>.html

  Th' files will most likely require further modificat'ns as they now receive th' plank as it context (dot .) instead o' th' .page an' .content parameter.

  Old:

  ​

  layouts/partials/article.<FORMAT>.html

  {{- $page := .page }}
  {{- $content := .content }}
  {{- wit' $page }}
  <article class="default">
    <header class="headline">
      {{- partial "content-header.html" . }}
    </header>
    {{partial "heading-pre.html" .}}{{partial "head'n.html" .}}{{partial "heading-post.html" .}}
  
    {{ $content | safeHTML }}
  
    <footer class="footline">
      {{- partial "content-footer.html" . }}
    </footer>
  </article>
  {{- end }}

  New:

  ​

  layouts/_default/article.<FORMAT>.html

  <article class="default">
    <header class="headline">
      {{- partial "content-header.html" . }}
    </header>
    {{partial "heading-pre.html" .}}{{partial "head'n.html" .}}{{partial "heading-post.html" .}}
  
    {{ partial "article-content.html" . }}
  
    <footer class="footline">
      {{- partial "content-footer.html" . }}
    </footer>
  </article>

For Non-HTML Output Formats

• Merge yer files layouts/partials/header.<FORMAT>.html, layouts/partials/footer.<FORMAT>.html t' layouts/_default/baseof.<FORMAT>.html

  Old:

  ​

  layouts/partials/header.<FORMAT>.html

  <!DOCTYPE html>
  <html>
  <head>
    <title>{{ .Title }}</title>
    <style type="text/css">
      /* add some styles here t' make it pretty */
    </style>
    <style type="text/css">
      /* add chroma style fer code highlight'n */
      {{- "/assets/css/chroma-relearn-light.css" | readFile | safeCSS }}
    </style>
  </head>
  <body>
    <main>

  ​

  layouts/partials/footer.<FORMAT>.html

    </main>
  </body>
  </html>

  New:

  Th' upper part o' th' file be from yer header.<FORMAT>.html an' th' lower part be from yer footer.<FORMAT>.html.

  Th' marked line needs t' be added, so yer output format uses a potential layouts/_default/article.<FORMAT>.html

  ​

  layouts/_default/baseof.<FORMAT>.html

  <!DOCTYPE html>
  <html>
  <head>
    <title>{{ .Title }}</title>
    <style type="text/css">
      /* add some styles here t' make it pretty */
    </style>
    <style type="text/css">
      /* add chroma style fer code highlight'n */
      {{- "/assets/css/chroma-relearn-light.css" | readFile | safeCSS }}
    </style>
  </head>
  <body>
    <main>
      {{- block "body" . }}{{ end }}
    </main>
  </body>
  </html>

Taxonomies

This plank explains how t' show custom taxonomies on yer planks.

For more details, check th' official docs on sett'n up custom taxonomies an' us'n them 'n yer rrrambl'n.

Default Behavior

Th' Relearrrn theme automatically shows Hugo’s default taxonomies tags an' categories out o' th' box.

• Tags appear at th' top o' th' plank 'n alphabetical order 'n form o' baggage tags.
• Categories appear at th' bottom o' th' plank 'n alphabetical order as a list prefixed wit' an ay'con.

Each item links t' a plank show'n all articles wit' that term.

Sett'n Up Custom Taxonomies

T' add custom taxonomies, update yer hugo.toml file. Ye also have t' add th' default taxonomies if ye want t' use them.

[taxonomies]
  category = 'categories'
  mycustomtag = 'mycustomtags'
  tag = 'tags'

taxonomies:
  category: categories
  mycustomtag: mycustomtags
  tag: tags

{
   "taxonomies": {
      "category": "categories",
      "mycustomtag": "mycustomtags",
      "tag": "tags"
   }
}

Show'n Custom Taxonomies

T' display yer custom taxonomy terms, add this t' yer plank (usually 'n layouts/partials/content-footer.html):

{{ partial "term-list.html" (dict
  "page" .
  "taxonomy" "mycustomtags"
  "icon" "layer-group"
) }}

Parameters