# Rambl'n :: Cap'n Hugo Relearrrn Theme
Documentation for Hugo Relearn Theme
Author: Sören Weber

T' chapterrr 2

# Rambl'n

Arrr! Pirrrates

Fello' pirrates, be awarrre some stuff may not work fer us in this trrranslat'n. Like table of rrramblings, see'ng Merrrmaids, do'ng math or chemistrrry and stuff.

Find out how t' create an' org'nize yer rrrambl'n quickly an' intuitively.

# Subsct'ns o' Rambl'n

# Planks orrrganizat'n

Arrr! Pirrrates

Fello' pirrates, be awarrre some stuff may not work fer us in this trrranslat'n. Like table of rrramblings, see'ng Merrrmaids, do'ng math or chemistrrry and stuff.

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

Avast

`_index.md` be required 'n each folder, it’s yer “folder home page”

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

## Frontmatter Configurat'n

Each Cap'n Hugo plank has t' define a frontmatter 'n toml, yaml or json. This ship will use toml 'n all cases.

Th' Relearrrn theme uses th' follow'n parameters on top o' Cap'n Hugo ones:

    +++
    # T'ble o' contents (toc) be enabled by default. Set this parameter t' true t' dis'ble it.
    # Avast: Toc be always disabled fer chapter planks
    disableToc = false
    # If set, this will be used fer th' page's menu entry (instead o' th' `title` attribute)
    menuTitle = ""
    # If set, this will explicitly override common rules fer th' expand state o' a page's menu entry
    alwaysopen = true
    # If set, this will explicitly override common rules fer th' sort'n order o' a page's submenu entries
    ordersectionsby = "title"
    # Th' title o' th' plank head'n will be prefixed by this HTML rrrambl'n
    headingPre = ""
    # Th' title o' th' plank head'n will be postfixed by this HTML rrrambl'n
    headingPost = ""
    # Th' title o' th' plank 'n menu will be prefixed by this HTML rrrambl'n
    menuPre = ""
    # Th' title o' th' plank 'n menu will be postfixed by this HTML rrrambl'n
    menuPost = ""
    # Hide a menu entry by sett'n this t' true
    hidden = false
    # Display name o' this plank modifier. If set, it will be displayed 'n th' footer.
    LastModifierDisplayName = ""
    # Email o' this plank modifier. If set wit' LastModifierDisplayName, it will be displayed 'n th' footer
    LastModifierEmail = ""
    +++

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

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

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

### Us'n a custom title fer menu entries

By default, th' Relearrrn theme will use a page’s `title` attribute fer th' menu item (or `linkTitle` if defined).

But a page’s title has t' be descriptive on its own while th' menu be a hierarchy. We’ve added th' `menuTitle` parameter fer that purpose:

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

    +++
    title = "Install on Linux"
    menuTitle = "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.

# Arrrchetypes

Arrr! Pirrrates

Fello' pirrates, be awarrre some stuff may not work fer us in this trrranslat'n. Like table of rrramblings, see'ng Merrrmaids, do'ng math or chemistrrry and stuff.

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 = X
    +++

    Lorem Ipsum.

Replace th' `X` wit' a number. Because this 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 }}"
    weight = X
    +++

    Lorem Ipsum.

Replace th' `X` wit' a number or delete th' whole `weight` parameter entirely.

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

Name | Notes
--- | ---
styleclass | Defines a set o' CSS classes t' be added t' th' HTML’s `<main>` element. Ye can use these classes t' define own CSS rules 'n yer `custom-header.html`
article | Defines th' HTML how t' render yer rrrambl'n

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

Arrr! Pirrrates

Fello' pirrates, be awarrre some stuff may not work fer us in this trrranslat'n. Like table of rrramblings, see'ng Merrrmaids, do'ng math or chemistrrry and stuff.

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

Without further delay, let us go over th' main elements o' Marrrkdown an' what th' result'n HTML looks like:

Smarrrt Arrrse

Bookmark this plank an' th' official Commonmark reference fer easy future reference!

## Paragraphs

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

Any text not start'n wit' a special sign be written as normal, plain text paragraph block an' must be separated t' its adjacent blocks by empty lines.

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

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

Result

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

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

## Head'ns

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

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

    # h1 Head'n

    ## h2 Head'n

    ### h3 Head'n

    #### h4 Head'n

    ##### h5 Head'n

    ###### h6 Head'n

Result

# h1 Head'n

## h2 Head'n

### h3 Head'n

#### h4 Head'n

##### h5 Head'n

###### h6 Head'n

## Horizontal Rules

T' further structure yer rrrambl'n ye can add horizontal rules. They create a “thematic break” between paragraph blocks. In Marrrkdown, ye can create it wit' three consecutive dashes `---`.

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

    ---

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

Result

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

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

## Text Markers

### Bold

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

    I am rendered wit' **bold text**

Result

I am rendered wit' bold text

### Italics

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

    I am rendered wit' _italicized text_

Result

I am rendered wit' italicized text

### Strikethrough

In GFM (GitHub Flavored Markdown) ye can do strikethroughs by enclos'n text wit' two tildes `~~`.

    ~~Strike through this text~~

Result

Strike through this text

## Text substitut'n

This Marrrkdown dialect supports an extension t' combine multiple punctuat'n characters t' single typographic entities. This will only be applied t' text outside o' code blocks or inline code.

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

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

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

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

Result

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

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

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

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

## Lists

### Unordered

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

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

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

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

Result

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

### Ordered

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

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

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

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

Result

1. Lorem ipsum dolor sit amet
2. Consectetur adipisc'n elit
   1. Integer molestie lorem at massa
   2. Facilisis 'n pretium nisl aliquet
3. Nulla volutpat aliquam velit
   1. Faucibus porta lacus fringilla vel
   2. Aenean sit amet erat nunc
4. Eget porttitor lorem

### Tasks

In GFM (GitHub Flavored Markdown) ye can add task lists result'n 'n checked or unchecked non-click'ble items

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

Result

- Basic Test
- More Tests
  - View
  - Hear
  - Smell

### Defint'ns

This Marrrkdown dialect supports an extension t' add defint'n lists. Definit'n lists be made o' terms an' definit'ns o' these terms, much like 'n a dictionary.

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

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

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

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

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

      Ye can't make juice out o' it.

Result

Apple
  Pomaceous fruit o' plants o' th' genus Malus 'n th' family Rosaceae.
  An American computer company.
Orange
  Th' fruit o' an evergreen tree o' th' genus Citrus.

  Ye can make juice out o' it.

  A telecommunicat'n company.

  Ye can’t make juice out o' it.

## Code

### Inline Code

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

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

Result

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

### Indented Code Block

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

    Be impressed by my advanced code:

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

Result

Be impressed by my advanced code:

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

### Fenced Code Block

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

In GFM (GitHub Flavored Markdown) ye can also add a language specifier directly aft 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
    grunt.initConfig({
      assemble: {
        opt'ns: {
          assets: 'docs/assets',
          data: 'src/data/*.{json,yml}',
          helpers: 'src/custom-helpers.js',
          partials: ['src/partials/**/*.{hbs,md}']
        },
        planks: {
          opt'ns: {
            layout: 'default.hbs'
          },
          files: {
            './': ['src/templates/pages/index.hbs']
          }
        }
      }
    };
    ```

Result

    grunt.initConfig({
      assemble: {
        opt'ns: {
          assets: 'docs/assets',
          data: 'src/data/*.{json,yml}',
          helpers: 'src/custom-helpers.js',
          partials: ['src/partials/**/*.{hbs,md}']
        },
        planks: {
          opt'ns: {
            layout: 'default.hbs'
          },
          files: {
            './': ['src/templates/pages/index.hbs']
          }
        }
      }
    };

## Tables

In GFM (GitHub Flavored Markdown) ye can create tables by add'n pipes as dividers between each cell, an' by add'n a line o' dashes (also separated by bars) beneath th' header. Avast that th' pipes do not need t' be vertically aligned.

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

Result

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

### Aligned Columns

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

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

Result

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

## Blockquotes

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 augue, aliquam non hendrerit ac, commodo vel nisi.
    >
    > > Sed adipisc'n elit vitae augue consectetur a gravida nunc vehicula. Donec auctor odio non est accumsan facilisis. Aliquam id turpis 'n dolor tincidunt mollis ac eu diam.
    >
    > Mauris sit amet ligula egestas, feugiat metus tincidunt, luctus libero. Donec congue finibus tempor. Vestibulum aliquet sollicitudin erat, ut aliquet purus posuere luctus.

Result

> Donec massa lacus, ultricies a ullamcorper 'n, fermentum sed augue. Nunc augue 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.

## Links

### Autolink

In GFM (GitHub Flavored Markdown) absolute URLs will automatically be converted into a link.

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

Result

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

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

Result

Assemble

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

Result

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"

Result

Example

### Footnotes

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

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

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

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

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

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

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

        Blue light glows blue.

Result

That’s some text wit' a footnote1

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

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

2. Anyth'n o' interest goes here.

   Blue light glows blue. ↩︎

## Images

### Basic Images

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

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

Result

### Image wit' Tooltip

Like links, images can also be given a tooltip.

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

Result

### Image References

Images can also be linked by reference ID t' later define th' URL locat'n. This simplyfies writ'n if ye want t' use an image more than once 'n a document.

    ![La Forge][laforge]

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

Result

### Further Image Formatt'n

This theme allows additional non-standard formatt'n by sett'n query parameter at th' end o' th' image URL.

#### Resiz'n

Add query parameter `width` and/or `height` t' th' link image t' resize th' image. Values be CSS values (default be `auto`).

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

Result

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

Result

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

Result

#### CSS Classes

Add a query parameter `classes` t' th' link image t' add CSS classes. Add some o' th' predefined values or even define yer own 'n yer CSS.

##### Shadow

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

Result

##### Border

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

Result

##### Left

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

Result

##### Right

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

Result

##### Inline

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

Result

##### Combinat'n

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

Result

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

Result

# Code highlight'n

Arrr! Pirrrates

Fello' pirrates, be awarrre some stuff may not work fer us in this trrranslat'n. Like table of rrramblings, see'ng Merrrmaids, do'ng math or chemistrrry and stuff.

Th' Relearrrn theme uses Hugo’s built-in rules highlight'n fer code.

## Marrrkdown rules

Wrap th' code block wit' three backticks an' th' name o' th' language. Highlight will try t' auto detect th' language if one be not provided.

    ```json
    [
      {
        "title": "apples",
        "count": [12000, 20000],
        "description": {"text": "...", "sensitive": false}
      },
      {
        "title": "oranges",
        "count": [17500, null],
        "description": {"text": "...", "sensitive": false}
      }
    ]
    ```

Renders t':

    [
      {
        "title": "apples",
        "count": [12000, 20000],
        "description": {"text": "...", "sensitive": false}
      },
      {
        "title": "oranges",
        "count": [17500, null],
        "description": {"text": "...", "sensitive": false}
      }
    ]

## Supported languages

Cap'n Hugo comes wit' a remark'ble list o' supported languages.

## Recommended configurat'n

Ye can choose a color theme from th' list o' supported themes an' add it 'n yer `config.toml`

    [marrrkup]
      [marrrkup.highlight]
        # if `guessSyntax = true`, there will be no unstyled code even if no language
        # was given BUT Merrrmaid an' Math codefences will not work anymore! So this be a
        # mandatory sett'n fer yer ship if ye want t' use Merrrmaid or Math codefences
        guessSyntax = false

        # choose a color theme or create yer own
        style = "base16-snazzy"

# Menu extrrra shorrrtcuts

Arrr! Pirrrates

Fello' pirrates, be awarrre some stuff may not work fer us in this trrranslat'n. Like table of rrramblings, see'ng Merrrmaids, do'ng math or chemistrrry and stuff.

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 `config.toml` an' add a `[[menu.shortcuts]]` entry fer each link yer want t' add.

Example from th' current website:

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

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

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

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

    [[menu.shortcuts]]
    name = "<i class='fas fa-fw fa-tags'></i> 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' `config.toml` file, prefix yer menu configurat'n by `Languages.<language-id>`.

Example from th' current website:

    [Languages]
      [Languages.en]
        title = "Hugo Relearrrn Theme"
        weight = 1
        languageName = "English"
        landingPageURL = "/"
        landingPageName = "<i class='fas fa-home'></i> Home"

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

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

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

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

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

      [Languages.pir]
        title = "Cap'n Hugo Relearrrn Theme"
        weight = 1
        languageName = "Arrr! Pirrrates"
        landingPageURL = "/pir/"
        landingPageName = "<i class='fas fa-home'></i> Arrr! Home"

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

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

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

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

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

Read more about hugo menu an' hugo multilingual menus

# Multilingual an' i18n

Arrr! Pirrrates

Fello' pirrates, be awarrre some stuff may not work fer us in this trrranslat'n. Like table of rrramblings, see'ng Merrrmaids, do'ng math or chemistrrry and stuff.

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

It provides:

- Translat'n str'ns fer default values (English, Arabic, Simplified Chinese, Traditional Chinese, Czech, Dutch, Finnish French, German, Hindi, Indonesian, Italian, Japanese, Korean, Polish, Portuguese, Russian, Spanish, Turkish, Vietnamese). Feel free t' contribute!
- 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 `config.toml` file.

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

Avast

Make sure yer default language be defined as th' first one 'n th' `[Languages]` array, as th' theme needs t' make assumpt'ns on it

    # English be th' default language
    defaultContentLanguage = "en"

    [Languages]
    [Languages.en]
    title = "Hugo Relearrrn Theme"
    weight = 1
    languageName = "English"

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

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`

Ahoi

Be aware that only translated planks be displayed 'n menu. It’s not replaced wit' default language rrrambl'n.

Smarrrt Arrrse

Use slug frontmatter parameter t' translate urls too.

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

Arrr

Although th' theme supports a wide variety o' supported languages, th' site’s search via th' Lunr search library does not. You’ll see error reports 'n yer browsers console log fer each unsupported language. Currently unsupported be:

- Czech
- Indonesian
- Polish

### 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 `config.toml` t' broaden search.

    [params]
      additionalContentLanguage = [ "en" ]

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

Avast

Keep 'n mind that th' language code required here, be th' base language code. E.g. if ye have additional rrrambl'n 'n `zh-CN`, ye have t' add just `zh` t' this parameter.

## 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 `config.toml`

    [params]
      # When us'n multilingual website, dis'ble th' switch language button.
      disableLanguageSwitchingButton = true

# Tags

Arrr! Pirrrates

Fello' pirrates, be awarrre some stuff may not work fer us in this trrranslat'n. Like table of rrramblings, see'ng Merrrmaids, do'ng math or chemistrrry and stuff.

Th' Relearrrn theme supports one default taxonomy o' Cap'n Hugo: th' tag feature.

## Configurat'n

Just add tags t' any plank:

    +++
    tags = ["tutorial", "theme"]
    title = "Theme tutorial"
    weight = 15
    +++

## Behavior

Th' tags be displayed at th' top o' th' plank, 'n their insert'n order.

Each tag be a link t' a Taxonomy plank display'n all th' articles wit' th' given tag.

## List all th' tags

In th' `config.toml` file ye can add a shortcut t' display all th' tags

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