Planks orrrganizat'n
Arrr! ☠ Pirrrates ☠
Fello' pirrates, be awarrre some featurrres may not work fer us in this trrranslat'n. Like table of rrramblings, some Merrrmaids 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.
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 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.
Default
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 = ""
+++
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> "
+++
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"
+++
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:
- Create an
_index.md document 'n rrrambl'n folder an' fill th' file wit' Marrrkdown rrrambl'n
- Create an
index.html file 'n th' static folder an' fill th' file wit' HTML rrrambl'n
- Configure yer server t' automatically redirect home plank t' one yer documentat'n plank
Marrrkdown rules
Arrr! ☠ Pirrrates ☠
Fello' pirrates, be awarrre some featurrres may not work fer us in this trrranslat'n. Like table of rrramblings, some Merrrmaids 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:
- Marrrkdown be simple t' learn, wit' minimal extra characters so it’s also quicker t' write rrrambl'n.
- Less chance o' errors when writ'n 'n Marrrkdown.
- Produces valid XHTML output.
- Keeps th' rrrambl'n an' th' visual display separate, so ye cannot mess up th' look o' yer ship.
- Write 'n any text editor or Marrrkdown applicat'n ye like.
- 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:
Head'ns
Head'ns from h1 through h6 be constructed wit' a # fer each level:
# h1 Head'n
## h2 Head'n
### h3 Head'n
#### h4 Head'n
##### h5 Head'n
###### h6 Head'n
Renders t':
h1 Head'n
h2 Head'n
h3 Head'n
h4 Head'n
h5 Head'n
h6 Head'n
HTML:
<h1>h1 Head'n</h1>
<h2>h2 Head'n</h2>
<h3>h3 Head'n</h3>
<h4>h4 Head'n</h4>
<h5>h5 Head'n</h5>
<h6>h6 Head'n</h6>
Comments should be HTML compat'ble
<!--
This be a comment
-->
Comment below should NOT be seen:
Horizontal Rules
Th' HTML <hr> element be fer creat'n a “thematic break” between paragraph-level elements. In Marrrkdown, ye can create a <hr> wit' --- - three consecutive dashes
renders t':
Paragraphs
Any text not start'n wit' a special sign be written as normal, plain text an' will be wrapped within <p></p> tags 'n th' rendered HTML.
So this body copy:
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.
renders t' this HTML:
<p>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.</p>
Text Markers
Bold
For emphasiz'n a snippet o' text wit' a heavier font-weight.
Th' follow'n snippet o' text be rendered as bold text.
**rendered as bold text**
renders t':
rendered as bold text
an' this HTML
<strong>rendered as bold text</strong>
Italics
For emphasiz'n a snippet o' text wit' italics.
Th' follow'n snippet o' text be rendered as italicized text.
_rendered as italicized text_
renders t':
rendered as italicized text
an' this HTML:
<em>rendered as italicized text</em>
Strikethrough
In GFM (GitHub flavored Markdown) ye can do strikethroughs.
~~Strike through this text.~~
Which renders t':
Strike through this text.
HTML:
<del>Strike through this text.</del>
Blockquotes
For quot'n blocks o' rrrambl'n from another source within yer document.
Add > before any text ye want t' quote.
> **Fusion Drive** combines a hard drive wit' a flash storage (solid-state drive) an' presents it as a single logical volume wit' th' space o' both drives combined.
Renders t':
Fusion Drive combines a hard drive wit' a flash storage (solid-state drive) an' presents it as a single logical volume wit' th' space o' both drives combined.
an' this HTML:
<blockquote>
<p><strong>Fusion Drive</strong> combines a hard drive wit' a flash storage (solid-state drive) an' presents it as a single logical volume wit' th' space o' both drives combined.</p>
</blockquote>
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.
Renders t':
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.
Lists
Unordered
A list o' items 'n which th' order o' th' items does not explicitly matter.
Ye may use any o' th' follow'n symbols t' denote bullets fer each list item:
* valid bullet
- valid bullet
+ valid bullet
For example
+ Lorem ipsum dolor sit amet
+ Consectetur adipisc'n elit
+ Integer molestie lorem at massa
+ Facilisis 'n pretium nisl aliquet
+ Nulla volutpat aliquam velit
- Phasellus iaculis neque
- Purus sodales ultricies
- Vestibulum laoreet porttitor sem
- Ac tristique libero volutpat at
+ Faucibus porta lacus fringilla vel
+ Aenean sit amet erat nunc
+ Eget porttitor lorem
Renders t':
- Lorem ipsum dolor sit amet
- Consectetur adipisc'n elit
- Integer molestie lorem at massa
- Facilisis 'n pretium nisl aliquet
- Nulla volutpat aliquam velit
- Phasellus iaculis neque
- Purus sodales ultricies
- Vestibulum laoreet porttitor sem
- Ac tristique libero volutpat at
- Faucibus porta lacus fringilla vel
- Aenean sit amet erat nunc
- Eget porttitor lorem
An' this HTML
<ul>
<li>Lorem ipsum dolor sit amet</li>
<li>Consectetur adipisc'n elit</li>
<li>Integer molestie lorem at massa</li>
<li>Facilisis 'n pretium nisl aliquet</li>
<li>Nulla volutpat aliquam velit
<ul>
<li>Phasellus iaculis neque</li>
<li>Purus sodales ultricies</li>
<li>Vestibulum laoreet porttitor sem</li>
<li>Ac tristique libero volutpat at</li>
</ul>
</li>
<li>Faucibus porta lacus fringilla vel</li>
<li>Aenean sit amet erat nunc</li>
<li>Eget porttitor lorem</li>
</ul>
Ordered
A list o' items 'n which th' order o' items does explicitly matter.
1. Lorem ipsum dolor sit amet
4. Consectetur adipisc'n elit
2. Integer molestie lorem at massa
8. Facilisis 'n pretium nisl aliquet
4. Nulla volutpat aliquam velit
99. Faucibus porta lacus fringilla vel
21. Aenean sit amet erat nunc
6. Eget porttitor lorem
Renders t':
- Lorem ipsum dolor sit amet
- Consectetur adipisc'n elit
- Integer molestie lorem at massa
- Facilisis 'n pretium nisl aliquet
- Nulla volutpat aliquam velit
- Faucibus porta lacus fringilla vel
- Aenean sit amet erat nunc
- Eget porttitor lorem
An' this HTML:
<ol>
<li>Lorem ipsum dolor sit amet</li>
<li>Consectetur adipisc'n elit</li>
<li>Integer molestie lorem at massa</li>
<li>Facilisis 'n pretium nisl aliquet</li>
<li>Nulla volutpat aliquam velit</li>
<li>Faucibus porta lacus fringilla vel</li>
<li>Aenean sit amet erat nunc</li>
<li>Eget porttitor lorem</li>
</ol>
Smarrrt Arrrse
If ye just use 1. fer each number, Marrrkdown will automatically number each item. For example:
1. Lorem ipsum dolor sit amet
1. Consectetur adipisc'n elit
1. Integer molestie lorem at massa
1. Facilisis 'n pretium nisl aliquet
1. Nulla volutpat aliquam velit
1. Faucibus porta lacus fringilla vel
1. Aenean sit amet erat nunc
1. Eget porttitor lorem
Renders t':
- Lorem ipsum dolor sit amet
- Consectetur adipisc'n elit
- Integer molestie lorem at massa
- Facilisis 'n pretium nisl aliquet
- Nulla volutpat aliquam velit
- Faucibus porta lacus fringilla vel
- Aenean sit amet erat nunc
- Eget porttitor lorem
Code
Inline code
Wrap inline snippets o' code wit' `.
In this example, `<div></div>` should be wrapped as **code**.
Renders t':
In this example, <div></div> should be wrapped as code.
HTML:
<p>In this example, <code><div></div></code> should be wrapped as <strong>code</strong>.</p>
Indented code
Or indent several lines o' code by at least two spaces, as 'n:
// Some comments
line 1 o' code
line 2 o' code
line 3 o' code
Renders t':
// Some comments
line 1 o' code
line 2 o' code
line 3 o' code
HTML:
<pre>
<code>
// Some comments
line 1 o' code
line 2 o' code
line 3 o' code
</code>
</pre>
Block code “fences”
Use “fences” ``` t' block 'n multiple lines o' code.
```
Sample text here...
```
HTML:
<pre>
<code>Sample text here...</code>
</pre>
Rules highlight'n
GFM, or “GitHub Flavored Markdown” also supports rules highlight'n. T' activate it, usually ye simply add th' file extension o' th' language ye want t' use directly aft th' first code “fence”, ```js, an' rules highlight'n will automatically be applied 'n th' rendered HTML.
See Code Highlight'n fer additional documentat'n.
For example, t' apply rules highlight'n t' JavaScript code:
```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']
}
}
}
};
```
Renders t':
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
Tables be created 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. |
Renders t':
| 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. |
An' this HTML:
<t'ble>
<tr>
<th>Opt'n</th>
<th>Descript'n</th>
</tr>
<tr>
<td>data</td>
<td>path t' data files t' supply th' data that will be passed into templates.</td>
</tr>
<tr>
<td>engine</td>
<td>engine t' be used fer process'n templates. Handlebars be th' default.</td>
</tr>
<tr>
<td>ext</td>
<td>extension t' be used fer dest files.</td>
</tr>
</t'ble>
Right aligned text
Add'n a colon on th' right side o' th' dashes below any head'n will right align text fer that column.
| 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. |
| 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. |
Two tables adjacent
| Opt'n |
Descript'n |
| ext |
extension t' be used fer dest files. |
| Opt'n |
Descript'n |
| ext |
extension t' be used fer dest files. |
Links
Basic link
[Assemble](http://assemble.io)
Renders t' (hover over th' link, there be no tooltip):
Assemble
HTML:
<a href="http://assemble.io">Assemble</a>
[Upstage](https://github.com/upstage/ "Visit Upstage!")
Renders t' (hover over th' link, there should be a tooltip):
Upstage
HTML:
<a href="https://github.com/upstage/" title="Visit Upstage!">Upstage</a>
Named Anchors
Named anchors en'ble ye t' jump t' th' specified anchor point on th' same plank. For example, each o' these chapters:
# T'ble o' Contents
* [Chapter 1](#chapter-1)
* [Chapter 2](#chapter-2)
* [Chapter 3](#chapter-3)
will jump t' these sections:
## Chapter 1 <a id="chapter-1"></a>
Rrrambl'n fer chapter one.
## Chapter 2 <a id="chapter-2"></a>
Rrrambl'n fer chapter one.
## Chapter 3 <a id="chapter-3"></a>
Rrrambl'n fer chapter one.
NOTE that specific placement o' th' anchor tag seems t' be arbitrary. They be placed inline here since it seems t' be unobtrusive, an' it works.
Images
Images have a similar rules t' links but include a preced'n exclamat'n point.
or
Like links, Images also have a footnote style rules
Alternative usage : note images
Wit' a reference later 'n th' document defin'n th' URL locat'n:
[id]: https://octodex.github.com/images/dojocat.jpg "The Dojocat"
Th' Cap'n Hugo Marrrkdown parser supports additional non-standard functionality.
Resiz'n image
Add HTTP parameters width and/or height t' th' link image t' resize th' image. Values be CSS values (default be auto).
Add CSS classes
Add a HTTP classes parameter t' th' link image t' add CSS classes. shadowan' border be avail'ble but ye could define other ones.
Lightbox
Add a HTTP featherlight parameter t' th' link image t' dis'ble lightbox. By default lightbox be enabled us'n th' featherlight.js plugin. Ye can dis'ble this by defin'n featherlight t' false.
