Page Designs

Plank designs be used t' provide different layouts fer a given output format. If ye instead want t' provide a new output format, th' theme got ye covered as well.

A plank be displayed by exactly one plank design fer each output format, be represented by Hugo’s reserved type front matter an' uses Hugo’s rrrambl'n view mechanism.

A plank design usually consists o'

Arrr

Don’t use Hugo’s reserved type opt'n 'n yer modificat'ns fer other functionality!

Us'n a Plank Design

Regardless o' shipped or custom plank designs, ye be us'n them 'n th' same way. Either by manually sett'n th' type front matter t' th' value o' th' plank design or by us'n an archetype dur'n creat'n o' a new plank.

If no type be set 'n yer front matter or th' plank design doesn’t exist fer a given output format, th' plank be treated as if type='default' was set.

Th' Relearrrn theme ships wit' th' plank designs home, chapter, an' default fer th' HTML output format.

Th' shipped print an' markdown output formats only display us'n th' default plank design.

Creat'n a Plank Design

Suppose ye be writ'n a documentat'n ship fer some software. Each time a new release be created, ye be add'n a new releasenotes plank t' yer ship. Those planks should contain a common disclaimer at th' top. Ye neither want t' copy th' text into each new file nor want ye t' use a shortcode but create a plank design called releasenotes.

  1. Choose a name (here, releasenotes)

  2. Create a rrrambl'n view file at layouts/releasenotes/article.html

    ​
    <article class="releasenotes">
  <header class="headline">
    {{partial "content-header.html" .}}
  </header>
  {{partial "heading-pre.html" .}}{{partial "head'n.html" .}}{{partial "heading-post.html" .}}
  <p class="disclaimer">
    This software release comes without any warranty!
  </p>
  {{partial "article-content.html" .}}
  <footer class="footline">
    {{partial "content-footer.html" .}}
  </footer>
</article>

    Th' marked lines be yer customizat'ns, th' rest o' th' file was copied over from th' default implementat'n o' layouts/_default/article.html

    In this file, ye can cust'mize th' plank structure as needed. For HTML based output formats, typically you’ll want t':

    • Set a class at th' article element fer custom CSS styles
    • Call {{ partial "article-content.html" . }} t' show yer plank rrrambl'n

  3. Optional: create an archetype file at archetypes/releasenotes.md

    ​
    +++
title = "{{ replace .Name "-" " " | title }}"
type = "releasenotes"
+++

This be a new releasenote.

  4. Optional: add CSS 'n th' file layouts/partials/custom-header.html

    ​
    <style>
.releasenotes .disclaimer {
  background-color: pink;
  font-size: 72rem;
}
</style>

Partials

For any Output Format

These files be common fer all output formats.

  • layouts/<DESIGN>/baseof.<FORMAT>: Optional: Th' top most file ye could provide t' completely redefine th' whole design. No further partials will be called if ye don’ call them yourself

For HTML Output Formats

If ye want t' keep th' general HTML framework an' only change specific parts, ye can provide these files fer th' plank desingn fer th' HTML output format independently o' one another.

  • layouts/<DESIGN>/article.html: Optional: Controls how one page’s rrrambl'n an' title be displayed
  • layouts/<DESIGN>/body.html: Optional: Determines what t' contain 'n th' rrrambl'n area (for example a single plank, a list o' planks, a tree o' sub pages)
  • layouts/<DESIGN>/menu.html: Optional: Defines th' sidebar menu layout

For a real-world example, check out th' changelog plank design implementat'n

Migrat'n from Relearrrn 7

Cap'n Hugo 0.146 or newer required some changes t' th' themes file structure.

  • Move yer files from layouts/<DESIGN>/views up one level t' layouts/<DESIGN>

Migrat'n from Relearrrn 6

Previous t' Relearrrn 7, plank designs were defined by a proprietary solut'n unique t' th' theme. Depend'n on yer modificat'ns ye may have t' change some or all o' th' follow'n t' migrate t' Relearrrn 7’s plank designs.

  • In all yer *.md files, replace th' archetype front matter wit' type; th' value stays th' same; don’t forget yer archetype files if ye have some

  • Move yer files layouts/partials/archetypes/<DESIGN>/article.html t' layouts/<DESIGN>/article.html

    Th' files will most likely require further modificat'ns as they now receive th' plank as it context (dot .) instead o' th' .page an' .content parameter.

    Old:

    ​
    {{- $page := .page }}
{{- $content := .content }}
{{- wit' $page }}
<article class="default">
  <header class="headline">
    {{- partial "content-header.html" . }}
  </header>
  {{partial "heading-pre.html" .}}{{partial "head'n.html" .}}{{partial "heading-post.html" .}}

  {{ $content | safeHTML }}

  <footer class="footline">
    {{- partial "content-footer.html" . }}
  </footer>
</article>
{{- end }}

    New:

    ​
    <article class="default">
  <header class="headline">
    {{- partial "content-header.html" . }}
  </header>
  {{partial "heading-pre.html" .}}{{partial "head'n.html" .}}{{partial "heading-post.html" .}}

  {{ partial "article-content.html" . }}

  <footer class="footline">
    {{- partial "content-footer.html" . }}
  </footer>
</article>