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
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 = ""
# Override default values fer image effects, ye can even add yer own arbitrary effects t' th' list
[params.imageEffects]
  border = false
  lightbox = true
  shadow = false
+++

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

Title wit' icon Title wit' icon

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.