# Planks orrrganizat'n

Arrr

Fello' pirrates, be awarrre some featurrres may not work fer us in this trrranslat'n. Like table of rrramblings 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”

## Types

Th' Relearrrn theme defines two types o' planks. Default an' Chapter. Both can be used at any level o' th' documentat'n, th' only difference be'n layout display.

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 under it. Ye can define any HTML as prefix fer th' menu. In th' example below, it’s just a number but that could be an ay'con.

    +++
    chapter = true
    pre = "<b>1. </b>"
    title = "Basics"
    weight = 5
    +++

    ### Chapter 1

    # Basics

    Discover what this Cap'n Hugo theme be all about an' th' core-concepts behind it.

T' tell th' Relearrrn theme t' consider a plank as a chapter, set `chapter=true` 'n th' Front Matter o' th' plank.

A Default plank be any other rrrambl'n plank.

    +++
    title = "Installation"
    weight = 15
    +++

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 this great documentat'n fer beginners.

## Create yer project

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.

## Front Matter configurat'n

Each Cap'n Hugo plank has t' define a Front Matter '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 'n menu will be prefixed by this HTML rrrambl'n
    pre = ""
    # Th' title o' th' plank 'n menu will be postfixed by this HTML rrrambl'n
    post = ""
    # Set th' plank as a chapter, chang'n th' way it's displayed
    chapter = false
    # 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 `pre` param t' insert any HTML code before th' menu label. Th' example below uses th' GitHub ay'con.

    +++
    title = "GitHub repo"
    pre = "<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 recursivley
- all remain'n entries be not shown

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

## Yer Plank

T' configure yer plank, ye basically have three choices:

1. Create an `_index.md` document 'n `rrrambl'n` folder an' fill th' file wit' Marrrkdown rrrambl'n
2. Create an `index.html` file 'n th' `static` folder an' fill th' file wit' HTML rrrambl'n
3. Configure yer server t' automatically redirect home plank t' one yer documentat'n plank