archetypes: introducing hooks #300

archetypes/chapter.md

@@ -1,6 +1,5 @@
 +++
 archetype = "chapter"
-narrow = true
 title = "{{ replace .Name "-" " " | title }}"
 weight = X
 +++

exampleSite/content/basics/_index.en.md

@@ -1,6 +1,5 @@
 +++
 archetype = "chapter"
-narrow = true
 title = "Basics"
 weight = 1
 +++

exampleSite/content/basics/_index.pir.md

@@ -1,6 +1,5 @@
 +++
 archetype = "chapter"
-narrow = true
 title = "Basics"
 weight = 1
 +++

exampleSite/content/basics/migration/_index.en.md

@@ -16,9 +16,9 @@ This document shows you what's new in the latest release. For a detailed list of
 
 ## 5.0.0
 
-- **Change**: The way [archetypes]({{% relref "cont/archetypes" %}}) are used to generate output has changed. Your existing markdown files will still work like before and therefore you don't need to change anything after the upgrade.
+- **Change**: The way [archetypes]({{% relref "cont/archetypes" %}}) are used to generate output has changed. The new systems allows you, to redefine existing archetypes or even generate your own ones.
 
-  Nevertheless, it is recommended to adapt your existing markdown files to the new way as follows:
+  Your existing markdown files will still work like before and therefore you don't need to change anything after the upgrade. Nevertheless, it is recommended to adapt your existing markdown files to the new way as follows:
 
   - for your home page, add the frontmatter parameter `archetype = "home"` and remove the leading heading
 

exampleSite/content/cont/_index.en.md

@@ -1,6 +1,5 @@
 +++
 archetype = "chapter"
-narrow = true
 title = "Content"
 weight = 2
 +++

exampleSite/content/cont/_index.pir.md

@@ -1,6 +1,5 @@
 +++
 archetype = "chapter"
-narrow = true
 title = "Rambl'n"
 weight = 2
 +++

exampleSite/content/cont/archetypes/_index.en.md

@@ -49,7 +49,6 @@ This leads to a file with the following content
 ```markdown
 +++
 archetype = "chapter"
-narrow = true
 title = "{{ replace .Name "-" " " | title }}"
 weight = X
 +++
@@ -57,7 +56,7 @@ weight = X
 Lorem Ipsum.
 ```
 
-Replace the `X` with a number. Because this number will be used to generate the subtitle of the content page, set the number to a consecutive value starting at 1 for each new chapter level.
+Replace the `X` with a number. Because this number will be used to generate the subtitle of the chapter page, set the number to a consecutive value starting at 1 for each new chapter level.
 
 ### Default {#archetypes-default}
 
@@ -110,10 +109,19 @@ Afterwards you can generate new content files of that kind with the follwing com
 hugo new --kind <kind> <name>/_index.md
 ```
 
-### Partial
+### Partials
 
-To define how your archetypes are rendered, define a corresponding file in your project at `layouts/partials/archetypes/<kind>.html`.
-
-Take a look at the existing archetypes of this theme to get an idea how to utilize it.
+To define how your archetypes are rendered, define corresponding partial files in your projects directory `layouts/partials/archetypes/<kind>`.
 
 If you use an unknown archetype in your frontmatter, the `default` archetype will be used to generate the page.
+
+Related to each archetype, several _hook_ partial files can be given. If a partial for a specific hook is missing, no output is generated for this hook.
+
+The following hooks are used:
+
+| Name                 | Notes       |
+|:---------------------|:------------|
+| styleclass           | Defines a set of CSS classes to be added to the HTML's `<main>` element. You can use these classes to define own CSS rules in your `custom-header.html` |
+| article              | Defines the HTML how to render your content |
+
+Take a look at the existing archetypes of this theme to get an idea how to utilize it.

exampleSite/content/cont/pages/_index.en.md

@@ -76,8 +76,6 @@ headingPost = ""
 menuPre = ""
 # The title of the page in menu will be postfixed by this HTML content
 menuPost = ""
-# Makes the content more narrow, increases font-size and alignment
-narrow = false
 # Hide a menu entry by setting this to true
 hidden = false
 # Display name of this page modifier. If set, it will be displayed in the footer.

exampleSite/content/shortcodes/_index.en.md

@@ -1,6 +1,5 @@
 +++
 archetype = "chapter"
-narrow = true
 title = "Shortcodes"
 weight = 3
 +++

exampleSite/content/shortcodes/_index.pir.md

@@ -1,6 +1,5 @@
 +++
 archetype = "chapter"
-narrow = true
 title = "Shorrrtcodes"
 weight = 3
 +++

exampleSite/content/tests/_index.en.md

@@ -1,7 +1,6 @@
 +++
 archetype = "chapter"
 hidden = true
-narrow = true
 title = "Tests"
 weight = 4
 +++

exampleSite/content/tests/_index.pir.md

@@ -1,7 +1,6 @@
 +++
 archetype = "chapter"
 hidden = true
-narrow = true
 title = "Tests"
 weight = 4
 +++

layouts/_default/index.html

@@ -1,2 +1,2 @@
 {{- .Scratch.Set "relearnOutputFormat" "HTML" }}
-{{- partial "_index.html" . }}
+{{- partial "_main.html" . }}

layouts/_default/index.print.html

@@ -1,2 +1,2 @@
 {{- .Scratch.Set "relearnOutputFormat" "PRINT" }}
-{{- partial "_index.html" . }}
+{{- partial "_main.html" . }}

layouts/_default/list.html

@@ -1,2 +1,2 @@
 {{- .Scratch.Set "relearnOutputFormat" "HTML" }}
-{{- partial "_list.html" . }}
+{{- partial "_main.html" . }}

layouts/_default/list.print.html

@@ -1,2 +1,2 @@
 {{- .Scratch.Set "relearnOutputFormat" "PRINT" }}
-{{- partial "_list.html" . }}
+{{- partial "_main.html" . }}

layouts/_default/single.html

@@ -1,2 +1,2 @@
 {{- .Scratch.Set "relearnOutputFormat" "HTML" }}
-{{- partial "_single.html" . }}
+{{- partial "_main.html" . }}

layouts/_default/single.print.html

@@ -1,2 +1,2 @@
 {{- .Scratch.Set "relearnOutputFormat" "PRINT" }}
-{{- partial "_single.html" . }}
+{{- partial "_main.html" . }}

layouts/partials/_index.html

@@ -1,9 +0,0 @@
-{{- partial "header.html" . }}
-{{- if not .Site.Home.Content }}
-  {{- partial "initial.html" .Site.Home }}
-{{- else if eq (.Scratch.Get "relearnOutputFormat") "PRINT" }}
-  {{- partial "body.print.html" .Site.Home }}
-{{- else }}
-  {{- partial "body.html" .Site.Home }}
-{{- end }}
-{{- partial "footer.html" . }}

layouts/partials/_list.html

@@ -1,7 +0,0 @@
-{{- partial "header.html" . }}
-{{- if eq (.Scratch.Get "relearnOutputFormat") "PRINT" }}
-  {{- partial "body.print.html" . }}
-{{- else }}
-  {{- partial "body.html" . }}
-{{- end }}
-{{- partial "footer.html" . }}

layouts/partials/_main.html

@@ -1,5 +1,7 @@
 {{- partial "header.html" . }}
-{{- if eq (.Scratch.Get "relearnOutputFormat") "PRINT" }}
+{{- if not .File }}
+  {{- partial "initial.html" . }}
+{{- else if eq (.Scratch.Get "relearnOutputFormat") "PRINT" }}
   {{- partial "body.print.html" . }}
 {{- else }}
   {{- partial "body.html" . }}

layouts/partials/archetype.html

@@ -0,0 +1,14 @@
+{{- $archetype := "default" }}
+{{- if .page.Params.archetype }}
+  {{- $archetype = .page.Params.archetype }}
+{{- else if .page.Params.chapter }}
+  {{- $archetype = "deprecated-chapter" }}
+{{- else if .page.IsHome }}
+  {{- $archetype = "deprecated-home" }}
+{{- end }}
+{{- if not (fileExists (printf "/layouts/partials/archetypes/%s" $archetype)) }}
+  {{- $archetype = "default" }}
+{{- end }}
+{{- if (fileExists (printf "/layouts/partials/archetypes/%s/%s.html" $archetype .hook)) }}
+  {{- partial (printf "archetypes/%s/%s.html" $archetype .hook) . }}
+{{- end }}

layouts/partials/archetypes/chapter/article.html

@@ -1,9 +1,9 @@
 {{- $content := .content }}
 {{- with .page }}
           <article class="chapter">
+{{ partial "heading-pre.html" . }}<div class="article-subheading">{{ T "Chapter" .Params.Weight }}</div>
+<h1>{{ .Title }}</h1>{{ partial "heading-post.html" . }}
 
-{{- partial "heading-pre.html" . }}<div class="article-subheading">{{ T "Chapter" .Params.Weight }}</div>
-<h1>{{ .Title }}</h1>{{- partial "heading-post.html" . }}
 {{ $content | safeHTML }}
             <footer class="footline">
               {{- partial "content-footer.html" . }}

layouts/partials/archetypes/chapter/styleclass.html

@@ -0,0 +1 @@
+chapter narrow

layouts/partials/archetypes/default/article.html

@@ -1,8 +1,8 @@
 {{- $content := .content }}
 {{- with .page }}
           <article class="default">
+{{ partial "heading-pre.html" . }}<h1>{{ .Title }}</h1>{{ partial "heading-post.html" . }}
 
-{{- partial "heading-pre.html" . }}<h1>{{ .Title }}</h1>{{- partial "heading-post.html" . }}
 {{ $content | safeHTML }}
             <footer class="footline">
               {{- partial "content-footer.html" . }}

layouts/partials/archetypes/default/styleclass.html

@@ -0,0 +1 @@
+default

layouts/partials/archetypes/deprecated-chapter/styleclass.html

@@ -0,0 +1 @@
+chapter narrow

layouts/partials/archetypes/deprecated-home/styleclass.html

@@ -0,0 +1 @@
+home

layouts/partials/archetypes/home/article.html

@@ -1,8 +1,8 @@
 {{- $content := .content }}
 {{- with .page }}
           <article class="home">
+{{ partial "heading-pre.html" . }}<h1>{{ .Title }}</h1>{{ partial "heading-post.html" . }}
 
-{{- partial "heading-pre.html" . }}<h1>{{ .Title }}</h1>{{- partial "heading-post.html" . }}
 {{ $content | safeHTML }}
             <footer class="footline">
               {{- partial "content-footer.html" . }}

layouts/partials/archetypes/home/styleclass.html

@@ -0,0 +1 @@
+home

layouts/partials/article.html

@@ -1,12 +1 @@
-{{- $archetype := "default" }}
-{{- if .page.Params.archetype }}
-  {{- $archetype = .page.Params.archetype }}
-{{- else if .page.Params.chapter }}
-  {{- $archetype = "chapter-deprecated" }}
-{{- else if .page.IsHome }}
-  {{- $archetype = "home-deprecated" }}
-{{- end }}
-{{- if not (fileExists (printf "/layouts/partials/archetypes/%s.html" $archetype)) }}
-  {{- $archetype = "default" }}
-{{- end }}
-{{- partial (printf "archetypes/%s.html" $archetype) (dict "page" .page "content" .content) }}
+{{- partial "archetype.html" (dict "hook" "article" "page" .page "content" .content) }}

layouts/partials/header.html

@@ -104,7 +104,7 @@
         {{- end }}
         </div>
       </nav>
-      <main id="body-inner" class="highlightable{{if (or .Params.narrow .Params.chapter) }} narrow{{end}}" tabindex="-1">
+      <main id="body-inner" class="highlightable {{ partial "archetype.html" (dict "hook" "styleclass" "page" .) }}" tabindex="-1">
         <div class="flex-block-wrapper">
           <div id="head-tags">
 {{- partial "tags.html" . }}

layouts/partials/initial.html

@@ -1,13 +1,12 @@
           <article>
 
-<h1>Customize your own home page</h1>
+<h1>Create this Page</h1>
 <p>
-  The site is working. Don't forget to customize this page with your own. You typically have 3 choices :
+  You need to create a file for this page. You can either
 </p>
 <ul>
-  <li><b>1.</b> Create an _index.md document in <b>content</b> folder and fill it with Markdown content</li>
-  <li><b>2.</b> Create an <b>index.html</b> file in the <b>static</b> folder and fill the file with HTML content</li>
-  <li><b>3.</b> Configure your server to automatically redirect home page to one your documentation page</li>
+  <li>create an _index.md, index.md or otherly named markdown file (depending on Hugo's bundle type) in <b>content</b> folder and fill it with Markdown content</li>
+  <li>create an <b>index.html</b> file in the <b>static</b> folder and fill the file with HTML content</li>
 </ul>
 
             <footer class="footline">