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 t' true, th' menu 'n th' sidebar will be displayed 'n a collaps'ble tree view. Although th' functionality works wit' old browsers (IE11), th' display o' th' expander ay'cons be limited t' modern browsers
collapsibleMenu = false
# 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 = "weight"
# 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
+++

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

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

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 hierachical 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 # this adds th' expander t' th' menu entry if not already set 'n yer config.toml
[_build]
  render = "never" # no plank will be generated so th' plank does not have a url