planks orrrganizat'n

In Cap'n Hugo, planks be th' core o' yer ship. Once it be configured, planks be definitely th' added value t' yer documentat'n ship.

Folders

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

rrrambl'n
├── level-one
│   ├── level-two
│   │   ├── level-three
│   │   │   ├── level-four
│   │   │   │   ├── _index.md       <-- /level-one/level-two/level-three/level-four
│   │   │   │   ├── page-4-a.md     <-- /level-one/level-two/level-three/level-four/page-4-a
│   │   │   │   ├── page-4-b.md     <-- /level-one/level-two/level-three/level-four/page-4-b
│   │   │   │   └── page-4-c.md     <-- /level-one/level-two/level-three/level-four/page-4-c
│   │   │   ├── _index.md           <-- /level-one/level-two/level-three
│   │   │   ├── page-3-a.md         <-- /level-one/level-two/level-three/page-3-a
│   │   │   ├── page-3-b.md         <-- /level-one/level-two/level-three/page-3-b
│   │   │   └── page-3-c.md         <-- /level-one/level-two/level-three/page-3-c
│   │   ├── _index.md               <-- /level-one/level-two
│   │   ├── page-2-a.md             <-- /level-one/level-two/page-2-a
│   │   ├── page-2-b.md             <-- /level-one/level-two/page-2-b
│   │   └── page-2-c.md             <-- /level-one/level-two/page-2-c
│   ├── _index.md                   <-- /level-one
│   ├── page-1-a.md                 <-- /level-one/page-1-a
│   ├── page-1-b.md                 <-- /level-one/page-1-b
│   └── page-1-c.md                 <-- /level-one/page-1-c
├── _index.md                       <-- /
└── page-top.md                     <-- /page-top

Create yer project

Th' follow'n steps be here t' help ye initialize yer new website. If ye don’t know Cap'n Hugo at all, we strongly suggest ye t' train by follow'n great documentat'n fer beginners.

Cap'n Hugo provides a new command t' create a new website.

hugo new ship <new_project>

Th' Relearrrn theme provides archetypes t' help ye create this kind o' planks.

Frrrontmatter

Each Cap'n Hugo plank has t' define a frontmatter.

All Frontmatter Opt'ns

Th' values reflect example opt'ns. Th' defaults can be taken from th' annotated example below.

+++
LastModifierDisplayName = ''
LastModifierEmail = ''
alwaysopen = ''
collapsibleMenu = true
customMathJaxURL = ''
customMermaidURL = ''
customOpenapiURL = ''
descript'n = ''
disableBreadcrumb = false
disableMathJax = true
disableMermaid = true
disableNextPrev = false
disableOpenapi = true
disableToc = false
editURL = ''
headingPost = ''
headingPre = ''
hidden = false
highlightWrap = true
images = ['images/hero.png']
mathJaxInitialize = '{}'
menuPost = ''
menuPre = ''
mermaidInitialize = '{ "securityLevel": "loose" }'
mermaidZoom = true
ordersectionsby = 'weight'
title = 'Example Page'

[image]
  errorlevel = ''

[imageEffects]
  border = true
  lazy = true
  lightbox = true
  shadow = false

[include]
  errorlevel = ''

[link]
  errorlevel = ''

[openapi]
  errorlevel = ''
+++

---
LastModifierDisplayName: ""
LastModifierEmail: ""
alwaysopen: ""
collapsibleMenu: true
customMathJaxURL: ""
customMermaidURL: ""
customOpenapiURL: ""
descript'n: ""
disableBreadcrumb: false
disableMathJax: true
disableMermaid: true
disableNextPrev: false
disableOpenapi: true
disableToc: false
editURL: ""
headingPost: ""
headingPre: ""
hidden: false
highlightWrap: true
image:
  errorlevel: ""
imageEffects:
  border: true
  lazy: true
  lightbox: true
  shadow: false
images:
- images/hero.png
include:
  errorlevel: ""
link:
  errorlevel: ""
mathJaxInitialize: '{}'
menuPost: ""
menuPre: ""
mermaidInitialize: '{ "securityLevel": "loose" }'
mermaidZoom: true
openapi:
  errorlevel: ""
ordersectionsby: weight
title: Example Plank
---

{
   "LastModifierDisplayName": "",
   "LastModifierEmail": "",
   "alwaysopen": "",
   "collapsibleMenu": true,
   "customMathJaxURL": "",
   "customMermaidURL": "",
   "customOpenapiURL": "",
   "description": "",
   "disableBreadcrumb": false,
   "disableMathJax": true,
   "disableMermaid": true,
   "disableNextPrev": false,
   "disableOpenapi": true,
   "disableToc": false,
   "editURL": "",
   "headingPost": "",
   "headingPre": "",
   "hidden": false,
   "highlightWrap": true,
   "image": {
      "errorlevel": ""
   },
   "imageEffects": {
      "border": true,
      "lazy": true,
      "lightbox": true,
      "shadow": false
   },
   "images": [
      "images/hero.png"
   ],
   "include": {
      "errorlevel": ""
   },
   "link": {
      "errorlevel": ""
   },
   "mathJaxInitialize": "{}",
   "menuPost": "",
   "menuPre": "",
   "mermaidInitialize": "{ \"securityLevel\": \"loose\" }",
   "mermaidZoom": true,
   "openapi": {
      "errorlevel": ""
   },
   "ordersectionsby": "weight",
   "title": "Example Page"
}

Annotated Frontmatter Opt'ns

+++
# 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 = ""

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

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

# Hide th' t'ble 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 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.

# Prefix fer th' title 'n main 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 main menu.
# Default: not set
# Th' title o' th' plank 'n th' menu will be suffixed by this HTML rrrambl'n.
menuPost = ""

# Th' order o' main 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.
# If not set, th' set value o' yer site's hugo.toml be used.
collapsibleMenu = true

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Hidden planks
# These opt'ns configure how hidden planks be treated.
# A plank flagged as hidden, be only removed from th' main 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: true
imageEffects.lazy = true
# Default: true
imageEffects.lightbox = true
# Default: false
imageEffects.shadow = false

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Links
# These opt'ns configure how links be displayed.

# 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 = ""

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# 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 = "{}"

# Only board MathJax if needed.
# Default: true
# If a Math shortcode be found, th' opt'n will be ignored an'
# MathJax will be boarded regardlessly. Th' opt'n be still useful 'n case ye
# be us'n script'n t' set up yer graph. In this case no shortcode or
# Marrrkdown codefence be involved an' th' library be not boarded by default. In this case
# ye can set `disableMathJax=false` 'n yer frontmatter t' force th' library t'
# be boarded.
# If not set, th' set value o' yer site's hugo.toml be used.
disableMathJax = true

# 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\" }"

# Only board Merrrmaid if needed.
# Default: true
# If a Merrrmaid shortcode or Marrrkdown codefence be found, th' opt'n will be ignored an'
# Merrrmaid will be boarded regardlessly. Th' opt'n be still useful 'n case ye
# be us'n script'n t' set up yer graph. In this case no shortcode or
# Marrrkdown codefence be involved an' th' library be not boarded by default. In this case
# ye can set `disableMermaid=false` 'n yer frontmatter t' force th' library t'
# be boarded.
# If not set, th' set value o' yer site's hugo.toml be used.
disableMermaid = true

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

# Only board OpenAPI if needed.
# Default: true
# If a OpenAPI shortcode be found, th' opt'n will be ignored an'
# OpenAPI will be boarded regardlessly. Th' opt'n be still useful 'n case ye
# be us'n script'n t' set up yer graph. In this case no shortcode or
# Marrrkdown codefence be involved an' th' library be not boarded by default. In this case
# ye can set `disableOpenapi=false` 'n yer frontmatter t' force th' library t'
# be boarded.
# If not set, th' set value o' yer site's hugo.toml be used.
disableOpenapi = true

# 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 = ""
+++

Some Detailed Examples

Add Ay'con t' a Menu Entry

In th' plank frontmatter, add a menuPre param t' insert any HTML code before th' menu label. Th' example below uses th' GitHub ay'con.

+++
menuPre = "<i class='fab fa-github'></i> "
title = 'GitHub repo'
+++

---
menuPre: '<i class=''fab fa-github''></i> '
title: GitHub repo
---

{
   "menuPre": "\u003ci class='fab fa-github'\u003e\u003c/i\u003e ",
   "title": "GitHub repo"
}

Order'n Sibl'n Menu/Page Entries

Cap'n Hugo provides a flex'ble way t' handle order fer yer planks.

Th' simplest way be t' set weight parameter t' a number.

+++
title = 'My page'
weight = 5
+++

---
title: My plank
weight: 5
---

{
   "title": "My page",
   "weight": 5
}

Us'n a Custom Title fer Menu Entries

By default, th' Relearrrn theme will use a page’s title attribute fer th' menu item.

But a page’s title has t' be descriptive on its own while th' menu be a hierarchy. Cap'n Hugo adds th' linkTitle parameter fer that purpose:

For example (for a plank named content/install/linux.md):

+++
linkTitle = 'Linux'
title = 'Install on Linux'
+++

---
linkTitle: Linux
title: Install on Linux
---

{
   "linkTitle": "Linux",
   "title": "Install on Linux"
}

Override Expand State Rules fer Menu Entries

Ye can change how th' theme expands menu entries on th' side o' th' rrrambl'n wit' th' alwaysopen sett'n on a per plank basis. If alwaysopen=false fer any given entry, its children will not be shown 'n th' menu as long as it be not necessary fer th' sake o' navigat'n.

Th' theme generates th' menu based on th' follow'n rules:

• all parent entries o' th' active plank includ'n their sibl'ns be shown regardless o' any sett'ns
• immediate children entries o' th' active plank be shown regardless o' any sett'ns
• if not overridden, all other first level entries behave like they would have been given alwaysopen=false
• if not overridden, all other entries o' levels besides th' first behave like they would have been given alwaysopen=true
• all vis'ble entries show their immediate children entries if alwaysopen=true; this proceeds recursively
• all remain'n entries be not shown

Ye can see this feature 'n act'n on th' example plank fer children shortcode an' its children planks.

Dis'ble Sect'n Planks

Ye may want t' structure yer planks 'n a hierarchical way but don’t want t' generate planks fer those sections? Th' theme got ye covered.

T' stay wit' th' initial example: Suppose ye want level-one appear 'n th' sidebar but don’t want t' generate a plank fer it. So th' entry 'n th' sidebar should not be click'ble but should show an expander.

For this, open content/level-one/_index.md an' add th' follow'n frontmatter

+++
collapsibleMenu = true

[_build]
  render = 'never'
+++

---
_build:
  render: never
collapsibleMenu: true
---

{
   "_build": {
      "render": "never"
   },
   "collapsibleMenu": true
}

Arrrchetypes

Us'n th' command: hugo new [relative new rrrambl'n path], ye can start a rrrambl'n file wit' th' date an' title automatically set. While this be a welcome feature, active writers need more: archetypes. These be preconfigured skeleton planks wit' default frontmatter.

Th' Relearrrn theme defines some few archetypes o' planks but ye be free t' define new ones t' yer lik'n. All can be used at any level o' th' documentat'n, th' only difference be'n th' layout o' th' rrrambl'n.

Predefined Archetypes

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

This leads t' a file wit' th' follow'n rrrambl'n

+++
archetype = "home"
title = "{{ replace .Name "-" " " | title }}"
+++

Lorem Ipsum.

Chapter

A Chapter displays a plank meant t' be used as introduct'n fer a set o' child planks. Commonly, it contains a simple title an' a catch line t' define rrrambl'n that can be found below it.

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

hugo new --kind chapter <name>/_index.md

This leads t' a file wit' th' follow'n rrrambl'n

+++
archetype = "chapter"
title = "{{ replace .Name "-" " " | title }}"
weight = 1
+++

Lorem Ipsum.

Th' weight number 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 level.

Default

A Default plank be any other rrrambl'n plank. If ye set an unknown archetype 'n yer frontmatter, this archetype will be used t' generate th' plank.

T' create a default plank, run either one o' th' follow'n commands

hugo new <chapter>/<name>/_index.md

or

hugo new <chapter>/<name>.md

This leads t' a file wit' th' follow'n rrrambl'n

+++
title = "{{ replace .Name "-" " " | title }}"
+++

Lorem Ipsum.

Self defined Archetypes

If ye be 'n need o' further archetypes ye can define yer own or even redefine exist'n ones.

Template

Define a template file 'n yer project at archetypes/<kind>.md an' make sure it has at least th' frontmatter parameter fer that archetype like

+++
archetype = "<kind>"
+++

Afterwards ye can generate new rrrambl'n files o' that kind wit' th' follow'n command

hugo new --kind <kind> <name>/_index.md

Partials

T' define how yer archetypes be rendered, define correspond'n partial files 'n yer projects directory layouts/partials/archetypes/<kind>.

If ye use an unknown archetype 'n yer frontmatter, th' default archetype will be used t' generate th' plank.

Related t' each archetype, several hook partial files 'n th' form o' <hook>.html can be given inside each archetype directory. If a partial fer a specific hook be miss'n, no output be generated fer this hook.

Th' follow'n hooks be used:

Take a look at th' exist'n archetypes o' this theme t' get an idea how t' utilize it.

Output formats

Each hook file can be overridden o' a specific output format. Eg. if ye define a new output format PLAINTEXT 'n yer hugo.toml, ye can add a file layouts/partials/archetypes/default.plaintext.html t' change th' way how normal rrrambl'n be written fer that output format.

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

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:

• GFM Extension on top o' standard Marrrkdown adher'n t' GitHub Flavored Marrrkdown.

• PHP Extension on top o' standard Marrrkdown adher'n t' PHP Marrrkdown.

• Pants Extension by John Gruber adher'n t' SmartyPants.

• Cap'n Hugo Cap'n Hugo Extra Extension supported by Cap'n Hugo.

• Obsidian Extension implemented by Obsidian.

• HTML If th' usage o' HTML be allowed, th' theme supports styl'n fer further HTML elements.

• Relearrrn Extension specific t' this 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.

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

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.

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.

GitHub Styled Alerts

GFM Since Cap'n Hugo 0.132.0 GitHub styled 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, 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.

Obsidian Styled Alerts

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

> [!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

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**

Italics

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

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>

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

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

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.

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>?

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.

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

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

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

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.

Code

Inline Code

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

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

// 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" ]
};
```

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

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

Links

Autolink

GFM Absolute URLs will automatically be converted into a link.

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

Basic Link

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

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

Link wit' Tooltip

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!")

Link References

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"

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.

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)

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

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"

Image Effects

Relearrrn This theme allows additional non-standard formatt'n by sett'n query parameter at th' end o' th' image URL. Th' default behavior be configur'ble through yer hugo.toml or frontmatter parameter.

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)

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

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

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)

Border

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

Left

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

Right

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

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)

Combinat'n

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

Lightbox

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)

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

Image Effects

Th' theme supports non-standard image effects.

As described, ye can add this t' th' URL query parameter, but this may be cumbersome t' be done consistently fer th' whole plank.

Instead, ye can configure th' defaults 'n yer hugo.toml as well as overrid'n these default 'n th' planks frontmatter.

Explicitly set URL query parameter will override th' defaults 'n effect fer a plank.

Without any sett'ns 'n yer hugo.toml this defaults t'

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

params:
  imageEffects:
    border: false
    lazy: true
    lightbox: true
    shadow: false

{
   "params": {
      "imageEffects": {
         "border": false,
         "lazy": true,
         "lightbox": true,
         "shadow": false
      }
   }
}

This can be overridden 'n a planks frontmatter by eg.

+++
[imageEffects]
  border = true
+++

---
imageEffects:
  border: true
---

{
   "imageEffects": {
      "border": true
   }
}

Or by explicitly override sett'ns by URL query parameter

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

Th' sett'ns applied t' th' above image would be

bg-white = true
border = true
lazy = true
lightbox = false
shadow = false

bg-white: true
border: true
lazy: true
lightbox: false
shadow: false

{
   "bg-white": true,
   "border": true,
   "lazy": true,
   "lightbox": false,
   "shadow": false
}

This ends up 'n th' follow'n HTML whar' th' parameter be converted t' CSS classes.

<img src="https://octodex.github.com/images/minion.png?lightbox=false&bg-white=true" load'n="lazy" alt="Minion" class="bg-white border lazy nolightbox noshadow">

Extend'n

As ye can see 'n th' above example, th' bg-white parameter be not initially supported 'n th' themes default sett'ns. Nevertheless ye be free t' define arbitrary parameter by just add'n them t' th' URL query parameter or set them 'n yer hugo.toml or planks frontmatter.

Menu extrrra shorrrtcuts

Ye can define additional menu entries or shortcuts 'n th' navigat'n menu without any link t' rrrambl'n.

Basic configurat'n

Edit th' website configurat'n hugo.toml an' add a [[menu.shortcuts]] entry fer each link yer want t' add.

Example from th' current website:

[menu]
  [[menu.shortcuts]]
    identifier = 'ds'
    name = "<i class='fa-fw fab fa-github'></i> GitHub repo"
    url = 'https://github.com/McShelby/hugo-theme-relearn'
    weight = 10

  [[menu.shortcuts]]
    name = "<i class='fa-fw fas fa-camera'></i> Showcases"
    url = 'showcase/'
    weight = 11

  [[menu.shortcuts]]
    identifier = 'hugodoc'
    name = "<i class='fa-fw fas fa-bookmark'></i> Cap'n Hugo Documentation"
    url = 'https://gohugo.io/'
    weight = 20

  [[menu.shortcuts]]
    name = "<i class='fa-fw fas fa-bullhorn'></i> Credits"
    url = 'more/credits/'
    weight = 30

  [[menu.shortcuts]]
    name = "<i class='fa-fw fas fa-tags'></i> Tags"
    url = 'tags/'
    weight = 40

menu:
  shortcuts:
  - identifier: ds
    name: <i class='fa-fw fab fa-github'></i> GitHub repo
    url: https://github.com/McShelby/hugo-theme-relearn
    weight: 10
  - name: <i class='fa-fw fas fa-camera'></i> Showcases
    url: showcase/
    weight: 11
  - identifier: hugodoc
    name: <i class='fa-fw fas fa-bookmark'></i> Cap'n Hugo Documentat'n
    url: https://gohugo.io/
    weight: 20
  - name: <i class='fa-fw fas fa-bullhorn'></i> Credits
    url: more/credits/
    weight: 30
  - name: <i class='fa-fw fas fa-tags'></i> Tags
    url: tags/
    weight: 40

{
   "menu": {
      "shortcuts": [
         {
            "identifier": "ds",
            "name": "\u003ci class='fa-fw fab fa-github'\u003e\u003c/i\u003e GitHub repo",
            "url": "https://github.com/McShelby/hugo-theme-relearn",
            "weight": 10
         },
         {
            "name": "\u003ci class='fa-fw fas fa-camera'\u003e\u003c/i\u003e Showcases",
            "url": "showcase/",
            "weight": 11
         },
         {
            "identifier": "hugodoc",
            "name": "\u003ci class='fa-fw fas fa-bookmark'\u003e\u003c/i\u003e Cap'n Hugo Documentation",
            "url": "https://gohugo.io/",
            "weight": 20
         },
         {
            "name": "\u003ci class='fa-fw fas fa-bullhorn'\u003e\u003c/i\u003e Credits",
            "url": "more/credits/",
            "weight": 30
         },
         {
            "name": "\u003ci class='fa-fw fas fa-tags'\u003e\u003c/i\u003e Tags",
            "url": "tags/",
            "weight": 40
         }
      ]
   }
}

By default, shortcuts be preceded by a title. This title can be disabled by sett'n disableShortcutsTitle=true. However, if ye want t' keep th' title but change its value, it can be overridden by chang'n yer local i18n translat'n str'n configurat'n.

For example, 'n yer local i18n/en.toml file, add th' follow'n rrrambl'n

[Shortcuts-Title]
other = "<Your value>"

Read more about hugo menu an' hugo i18n translat'n str'ns

Configurat'n fer Multilingual mode

When us'n a multilingual website, ye can set different menus fer each language. In th' hugo.toml file, prefix yer menu configurat'n by Languages.<language-id>.

Example from th' current website:

[languages]
  [languages.en]
    languageName = 'English'
    title = 'Hugo Relearrrn Theme'
    weight = 1

    [languages.en.menu]
      [[languages.en.menu.shortcuts]]
        identifier = 'ds'
        name = "<i class='fa-fw fab fa-github'></i> GitHub repo"
        url = 'https://github.com/McShelby/hugo-theme-relearn'
        weight = 10

      [[languages.en.menu.shortcuts]]
        name = "<i class='fa-fw fas fa-camera'></i> Showcases"
        pageRef = 'showcase/'
        weight = 11

      [[languages.en.menu.shortcuts]]
        identifier = 'hugodoc'
        name = "<i class='fa-fw fas fa-bookmark'></i> Cap'n Hugo Documentation"
        url = 'https://gohugo.io/'
        weight = 20

      [[languages.en.menu.shortcuts]]
        name = "<i class='fa-fw fas fa-bullhorn'></i> Credits"
        pageRef = 'more/credits/'
        weight = 30

      [[languages.en.menu.shortcuts]]
        name = "<i class='fa-fw fas fa-tags'></i> Tags"
        pageRef = 'tags/'
        weight = 40

    [languages.en.params]
      landingPageName = "<i class='fa-fw fas fa-home'></i> Home"

  [languages.pir]
    languageName = 'Arrr! Pirrrates'
    title = "Cap'n Hugo Relearrrn Theme"
    weight = 1

    [languages.pir.menu]
      [[languages.pir.menu.shortcuts]]
        identifier = 'ds'
        name = "<i class='fa-fw fab fa-github'></i> GitHub repo"
        url = 'https://github.com/McShelby/hugo-theme-relearn'
        weight = 10

      [[languages.pir.menu.shortcuts]]
        name = "<i class='fa-fw fas fa-camera'></i> Showcases"
        pageRef = 'showcase/'
        weight = 11

      [[languages.pir.menu.shortcuts]]
        identifier = 'hugodoc'
        name = "<i class='fa-fw fas fa-bookmark'></i> Cap'n Hugo Documentat'n"
        url = 'https://gohugo.io/'
        weight = 20

      [[languages.pir.menu.shortcuts]]
        name = "<i class='fa-fw fas fa-bullhorn'></i> Crrredits"
        pageRef = 'more/credits/'
        weight = 30

      [[languages.pir.menu.shortcuts]]
        name = "<i class='fa-fw fas fa-tags'></i> Arrr! Tags"
        pageRef = 'tags/'
        weight = 40

    [languages.pir.params]
      landingPageName = "<i class='fa-fw fas fa-home'></i> Arrr! Home"

languages:
  en:
    languageName: English
    menu:
      shortcuts:
      - identifier: ds
        name: <i class='fa-fw fab fa-github'></i> GitHub repo
        url: https://github.com/McShelby/hugo-theme-relearn
        weight: 10
      - name: <i class='fa-fw fas fa-camera'></i> Showcases
        pageRef: showcase/
        weight: 11
      - identifier: hugodoc
        name: <i class='fa-fw fas fa-bookmark'></i> Cap'n Hugo Documentat'n
        url: https://gohugo.io/
        weight: 20
      - name: <i class='fa-fw fas fa-bullhorn'></i> Credits
        pageRef: more/credits/
        weight: 30
      - name: <i class='fa-fw fas fa-tags'></i> Tags
        pageRef: tags/
        weight: 40
    params:
      landingPageName: <i class='fa-fw fas fa-home'></i> Home
    title: Cap'n Hugo Relearrrn Theme
    weight: 1
  pir:
    languageName: Arrr! Pirrrates
    menu:
      shortcuts:
      - identifier: ds
        name: <i class='fa-fw fab fa-github'></i> GitHub repo
        url: https://github.com/McShelby/hugo-theme-relearn
        weight: 10
      - name: <i class='fa-fw fas fa-camera'></i> Showcases
        pageRef: showcase/
        weight: 11
      - identifier: hugodoc
        name: <i class='fa-fw fas fa-bookmark'></i> Cap'n Hugo Documentat'n
        url: https://gohugo.io/
        weight: 20
      - name: <i class='fa-fw fas fa-bullhorn'></i> Crrredits
        pageRef: more/credits/
        weight: 30
      - name: <i class='fa-fw fas fa-tags'></i> Arrr! Tags
        pageRef: tags/
        weight: 40
    params:
      landingPageName: <i class='fa-fw fas fa-home'></i> Arrr! Home
    title: Cap'n Hugo Relearrrn Theme
    weight: 1

{
   "languages": {
      "en": {
         "languageName": "English",
         "menu": {
            "shortcuts": [
               {
                  "identifier": "ds",
                  "name": "\u003ci class='fa-fw fab fa-github'\u003e\u003c/i\u003e GitHub repo",
                  "url": "https://github.com/McShelby/hugo-theme-relearn",
                  "weight": 10
               },
               {
                  "name": "\u003ci class='fa-fw fas fa-camera'\u003e\u003c/i\u003e Showcases",
                  "pageRef": "showcase/",
                  "weight": 11
               },
               {
                  "identifier": "hugodoc",
                  "name": "\u003ci class='fa-fw fas fa-bookmark'\u003e\u003c/i\u003e Cap'n Hugo Documentation",
                  "url": "https://gohugo.io/",
                  "weight": 20
               },
               {
                  "name": "\u003ci class='fa-fw fas fa-bullhorn'\u003e\u003c/i\u003e Credits",
                  "pageRef": "more/credits/",
                  "weight": 30
               },
               {
                  "name": "\u003ci class='fa-fw fas fa-tags'\u003e\u003c/i\u003e Tags",
                  "pageRef": "tags/",
                  "weight": 40
               }
            ]
         },
         "params": {
            "landingPageName": "\u003ci class='fa-fw fas fa-home'\u003e\u003c/i\u003e Home"
         },
         "title": "Hugo Relearrrn Theme",
         "weight": 1
      },
      "pir": {
         "languageName": "Arrr! Pirrrates",
         "menu": {
            "shortcuts": [
               {
                  "identifier": "ds",
                  "name": "\u003ci class='fa-fw fab fa-github'\u003e\u003c/i\u003e GitHub repo",
                  "url": "https://github.com/McShelby/hugo-theme-relearn",
                  "weight": 10
               },
               {
                  "name": "\u003ci class='fa-fw fas fa-camera'\u003e\u003c/i\u003e Showcases",
                  "pageRef": "showcase/",
                  "weight": 11
               },
               {
                  "identifier": "hugodoc",
                  "name": "\u003ci class='fa-fw fas fa-bookmark'\u003e\u003c/i\u003e Cap'n Hugo Documentat'n",
                  "url": "https://gohugo.io/",
                  "weight": 20
               },
               {
                  "name": "\u003ci class='fa-fw fas fa-bullhorn'\u003e\u003c/i\u003e Crrredits",
                  "pageRef": "more/credits/",
                  "weight": 30
               },
               {
                  "name": "\u003ci class='fa-fw fas fa-tags'\u003e\u003c/i\u003e Arrr! Tags",
                  "pageRef": "tags/",
                  "weight": 40
               }
            ]
         },
         "params": {
            "landingPageName": "\u003ci class='fa-fw fas fa-home'\u003e\u003c/i\u003e Arrr! Home"
         },
         "title": "Cap'n Hugo Relearrrn Theme",
         "weight": 1
      }
   }
}

Read more about hugo menu an' hugo multilingual menus

Shortcuts t' planks inside o' yer project

If ye have shortcuts t' planks inside o' yer project an' ye don’t want them t' show up 'n plank menu section, ye have two choices:

1. Make th' plank file fer th' shortcut a headless branch bundle (contained 'n its own subdirectory an' called _index.md) an' add th' follow'n frontmatter configurat'n t' th' file (see exampleSite’s content/showcase/_index.en.md). This causes its rrrambl'n t' not be ontained 'n th' sitemap.

   ​

   toml yaml json

   +++
   title = 'Showcase'
   
   [_build]
     list = 'never'
     publishResources = true
     render = 'always'
   +++

   ---
   _build:
     list: never
     publishResources: true
     render: always
   title: Showcase
   ---

   {
      "_build": {
         "list": "never",
         "publishResources": true,
         "render": "always"
      },
      "title": "Showcase"
   }

2. Store th' plank file fer th' shortcut below a parent headless branch bundle an' add th' follow'n frontmatter t' he parent (see exampleSite’s content/more/_index.en.md). Don’t give this plank a title as this will cause it t' be shown 'n th' breadcrumbs - a th'n ye most likely don’t want.

   ​

   toml yaml json

   +++
   [_build]
     list = 'never'
     publishResources = false
     render = 'never'
   +++

   ---
   _build:
     list: never
     publishResources: false
     render: never
   ---

   {
      "_build": {
         "list": "never",
         "publishResources": false,
         "render": "never"
      }
   }

   In this case, th' file itself can be a branch bundle, leaf bundle or simple plank (see exampleSite’s content/more/credits.en.md). This causes its rrrambl'n t' be contained 'n th' sitemap.

   ​

   toml yaml json

   +++
   title = 'Credits'
   +++

   ---
   title: Credits
   ---

   {
      "title": "Credits"
   }

Multilingual an' i18n

Th' Relearrrn theme be fully compat'ble wit' Cap'n Hugo multilingual mode.

• Avail'ble languages: Arabic, Simplified Chinese, Traditional Chinese, Czech, Dutch, English, Finnish, French, German, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Polish, Portuguese, Romanian, Russian, Spanish, Swahili, Turkish, Vietnamese. Feel free t' contribute!
• Full support fer languages written right t' left
• Automatic menu generat'n from multilingual rrrambl'n
• In-browser language switch'n

Basic configurat'n

Aft learn'n how Cap'n Hugo handle multilingual websites, define yer languages 'n yer hugo.toml file.

For example wit' current English an' Piratized English website.

defaultContentLanguage = 'en'

[languages]
  [languages.en]
    languageName = 'English'
    title = 'Hugo Relearrrn Theme'
    weight = 1

  [languages.pir]
    languageName = 'Arrr! Pirrrates'
    title = "Cap'n Hugo Relearrrn Theme"
    weight = 2

defaultContentLanguage: en
languages:
  en:
    languageName: English
    title: Cap'n Hugo Relearrrn Theme
    weight: 1
  pir:
    languageName: Arrr! Pirrrates
    title: Cap'n Hugo Relearrrn Theme
    weight: 2

{
   "defaultContentLanguage": "en",
   "languages": {
      "en": {
         "languageName": "English",
         "title": "Hugo Relearrrn Theme",
         "weight": 1
      },
      "pir": {
         "languageName": "Arrr! Pirrrates",
         "title": "Cap'n Hugo Relearrrn Theme",
         "weight": 2
      }
   }
}

Then, fer each new plank, append th' id o' th' language t' th' file.

• Single file my-page.md be split 'n two files:
  • 'n English: my-page.md
  • 'n Piratized English: my-page.pir.md
• Single file _index.md be split 'n two files:
  • 'n English: _index.md
  • 'n Piratized English: _index.pir.md

Search

In case each page’s rrrambl'n be written 'n one single language only, th' above configurat'n will already configure th' site’s search functionality correctly.

Search wit' mixed language support

In case yer page’s rrrambl'n contains text 'n multiple languages (e.g. ye be writ'n a Russian documentat'n fer yer english API), ye can add those languages t' yer hugo.toml t' broaden search.

[params]
  additionalContentLanguage = ['en']

params:
  additionalContentLanguage:
  - en

{
   "params": {
      "additionalContentLanguage": [
         "en"
      ]
   }
}

As this be an array, ye can add multiple additional languages.

Overwrite translat'n str'ns

Translat'ns str'ns be used fer common default values used 'n th' theme (Edit button, Search placeholder an' so on). Translat'ns be avail'ble 'n English an' Piratized English but ye may use another language or want t' override default values.

T' override these values, create a new file 'n yer local i18n folder i18n/<idlanguage>.toml an' inspire yourself from th' theme themes/hugo-theme-relearn/i18n/en.toml

Dis'ble language switch'n

Switch'n th' language 'n th' browser be a great feature, but fer some reasons ye may want t' dis'ble it.

Just set disableLanguageSwitchingButton=true 'n yer hugo.toml

[params]
  disableLanguageSwitchingButton = true

params:
  disableLanguageSwitchingButton: true

{
   "params": {
      "disableLanguageSwitchingButton": true
   }
}

Taxonomy

Th' Relearrrn theme supports Hugo’s default taxonomies tag an' category out o' th' box.

Configurat'n

Just add tags and/or categories t' any plank. They can be given as a single str'n or an array o' str'ns.

+++
categories = ['taxonomy', 'content']
tags = 'tutorial'
title = 'Taxonomy'
+++

---
categories:
- taxonomy
- rrrambl'n
tags: tutorial
title: Taxonomy
---

{
   "categories": [
      "taxonomy",
      "content"
   ],
   "tags": "tutorial",
   "title": "Taxonomy"
}

Behavior

Th' tags be displayed at th' top o' th' plank 'n alphabetical order.

Th' categories be displayed at th' bottom o' th' plank 'n alphabetical order 'n th' default implementat'n o' th' theme but can be customized by provid'n yer own content-footer.html partial.

Each item be a link t' a taxonomy plank display'n all th' articles wit' th' given term.

List all th' tags

In th' hugo.toml file ye can add a shortcut t' display all th' tags an' categories

[menu]
  [[menu.shortcuts]]
    name = "<i class='fa-fw fas fa-tags'></i> Tags"
    url = '/tags'

  [[menu.shortcuts]]
    name = "<i class='fa-fw fas fa-layer-group'></i> Categories"
    url = '/categories'

menu:
  shortcuts:
  - name: <i class='fa-fw fas fa-tags'></i> Tags
    url: /tags
  - name: <i class='fa-fw fas fa-layer-group'></i> Categories
    url: /categories

{
   "menu": {
      "shortcuts": [
         {
            "name": "\u003ci class='fa-fw fas fa-tags'\u003e\u003c/i\u003e Tags",
            "url": "/tags"
         },
         {
            "name": "\u003ci class='fa-fw fas fa-layer-group'\u003e\u003c/i\u003e Categories",
            "url": "/categories"
         }
      ]
   }
}

Customizat'n

If ye define custom taxonomies an' want t' display a list o' them somewhere on yer plank (often 'n th' layouts/partials/content-footer.html) ye can call a partial that does th' job fer ye:

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

Parameter