theme: allow overriding partials for output formats #308

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

@@ -9,8 +9,10 @@ In `themes/hugo-theme-relearn/layouts/partials/`, you will find all the partials
 
 This theme defines the following partials :
 
-- `header.html`: the header of the page. _Not meant to be overwritten_
+- `header.html`: the header of the page. See [output-formats](#output-formats)
-- `footer.html`: the footer of the page._Not meant to be overwritten_
+- `footer.html`: the footer of the page. See [output-formats](#output-formats)
+- `body.html`: the body of the page. The body may contain of one or many articles. See [output-formats](#output-formats)
+- `article.html`: the output for a single article, can contain elements around your content. See [output-formats](#output-formats)
 - `menu.html`: left menu. _Not meant to be overwritten_
 - `search.html`: search box. _Not meant to be overwritten_
 - `custom-header.html`: custom headers in page. Meant to be overwritten when adding CSS imports. Don't forget to include `style` HTML tag directive in your file.
@@ -81,3 +83,7 @@ If you want to switch the syntax highlightning theme together with your color va
 ### Roll your own
 
 If you are not happy with the shipped variants you can either copy one of the shipped files, edit them in a text editor and configure the `themeVariant` parameter in your `config.toml` or just use the [interactive variant generator]({{%relref "basics/generator" %}}).
+
+### Output formats
+
+Certain parts of the theme can be changed for support of your own [output formats](https://gohugo.io/templates/output-formats/). Eg. if you define a new output format `PLAINTEXT` in your `config.toml`, you can add a file `layouts/partials/header.plaintext.html` to change the way, the page header should look like for that output format.

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

@@ -115,7 +115,7 @@ To define how your archetypes are rendered, define corresponding partial files i
 
 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.
+Related to each archetype, several _hook_ partial files in the form of `<hook>.html` can be given inside each archetype directory. If a partial for a specific hook is missing, no output is generated for this hook.
 
 The following hooks are used:
 
@@ -125,3 +125,7 @@ The following hooks are used:
 | 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.
+
+#### Output formats
+
+Each hook file can be overridden of a specific [output format](https://gohugo.io/templates/output-formats/). Eg. if you define a new output format `PLAINTEXT` in your `config.toml`, you can add a file `layouts/partials/archetypes/default.plaintext.html` to change the way how normal content is written for that output format.

layouts/partials/_main.html

@@ -1,9 +1,7 @@
-{{- partial "header.html" . }}
+{{- partial "output-partial.html" (dict "base" "header" "page" . "parameter" .) }}
 {{- if not .File }}
-  {{- partial "initial.html" . }}
+  {{- partial "output-partial.html" (dict "base" "body" "page" . "parameter" (dict "page" . "content" (partial "initial.html" .))) }}
-{{- else if eq (.Scratch.Get "relearnOutputFormat") "PRINT" }}
-  {{- partial "body.print.html" . }}
 {{- else }}
-  {{- partial "body.html" . }}
+  {{- partial "output-partial.html" (dict "base" "body" "page" . "parameter" (dict "page" . "content" (partial "content.html" .))) }}
 {{- end }}
-{{- partial "footer.html" . }}
+{{- partial "output-partial.html" (dict "base" "footer" "page" . "parameter" .) }}

layouts/partials/archetype.html

@@ -1,14 +1,15 @@
+{{- $hook := .hook }}
+{{- $page := .page }}
+{{- $parameter := .parameter }}
 {{- $archetype := "default" }}
-{{- if .page.Params.archetype }}
+{{- if $page.Params.archetype }}
-  {{- $archetype = .page.Params.archetype }}
+  {{- $archetype = $page.Params.archetype }}
-{{- else if .page.Params.chapter }}
+{{- else if $page.Params.chapter }}
   {{- $archetype = "deprecated-chapter" }}
-{{- else if .page.IsHome }}
+{{- 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 "output-partial.html" (dict "base" (printf "archetypes/%s/%s" $archetype $hook) "page" $page "parameter" $parameter) }}
-  {{- partial (printf "archetypes/%s/%s.html" $archetype .hook) . }}
-{{- end }}

layouts/partials/article.html

@@ -1 +1,3 @@
-{{- partial "archetype.html" (dict "hook" "article" "page" .page "content" .content) }}
+{{- $page := .page }}
+{{- $content := .content }}
+{{- partial "archetype.html" (dict "hook" "article" "page" $page "parameter" (dict "page" $page "content" $content)) }}

layouts/partials/body.html

@@ -1 +1,3 @@
-{{- partial "article.html" (dict "page" . "content" .Content) }}
+{{- $page := .page }}
+{{- $content := .content }}
+{{- partial "output-partial.html" (dict "base" "article" "page" $page "parameter" (dict "page" $page "content" $content)) }}

layouts/partials/body.print.html

@@ -1,99 +1,3 @@
-{{- $currentNode := . }}
+{{- $page := .page }}
-{{- $isActive := .IsHome }}
+{{- $content := .content }}
-{{- $isShortcut := false }}
+{{- partial "nestedArticle.html" $page }}
-{{- $r_url := .RelPermalink }}
-{{- with .Site.Menus.shortcuts }}
-  {{- range sort . "Weight" }}
-    {{- $s_url := .URL | relLangURL }}
-    {{- if (eq $s_url $r_url) }}
-      {{- $isShortcut = true }}
-    {{- end }}
-  {{- end }}
-{{- end }}
-{{- $pages := .Site.Home.Sections }}
-{{- $defaultOrdersectionsby := .Site.Params.ordersectionsby | default "weight" }}
-{{- $currentOrdersectionsby := .Site.Home.Params.ordersectionsby | default $defaultOrdersectionsby }}
-{{- if $isShortcut }}
-  {{- template "section-print" dict "sect" . "currentnode" $currentNode }}
-{{- else }}
-  {{- if $isActive }}
-    {{- template "section-print" dict "sect" . "currentnode" $currentNode }}
-    {{- if or $pages }}
-            <section>
-    {{- end }}
-  {{- end }}
-  {{- if eq $currentOrdersectionsby "title" }}
-    {{- range $pages.ByTitle }}
-      {{- template "section-tree-print" dict "sect" . "currentnode" $currentNode "isActive" $isActive }}
-    {{- end }}
-  {{- else }}
-    {{- range $pages.ByWeight }}
-      {{- template "section-tree-print" dict "sect" . "currentnode" $currentNode "isActive" $isActive }}
-    {{- end }}
-  {{- end }}
-  {{- if $isActive }}
-    {{- if $pages }}
-            </section>
-    {{- end }}
-  {{- end }}
-{{- end }}
-{{- define "section-tree-print" }}
-  {{- $currentNode := .currentnode }}
-  {{- $isActive := .isActive }}
-  {{- $currentFileRelPermalink := .currentnode.RelPermalink }}
-  {{- with .sect }}
-    {{- $isSelf := eq .RelPermalink $currentFileRelPermalink }}
-    {{- $isAncestor := and (not $isSelf) (.IsAncestor $currentNode) }}
-    {{- $isActive = or $isSelf $isActive }}
-    {{- $pages := .Pages }}
-    {{- if .Page.IsHome }}
-      {{- $pages = .Sections }}
-    {{- else if .Page.Sections}}
-      {{- $pages = (.Pages | union .Sections) }}
-    {{- end }}
-    {{- $relearnIsHiddenFrom := index ($currentNode.Scratch.Get "relearnIsHiddenFrom") .RelPermalink }}
-    {{- $hidden := and $relearnIsHiddenFrom (not $.showhidden) (not $isSelf) (not $isAncestor) }}
-    {{- if $hidden }}
-    {{- else if or .IsSection .IsHome }}
-      {{- $defaultOrdersectionsby := .Site.Params.ordersectionsby | default "weight" }}
-      {{- $currentOrdersectionsby := .Params.ordersectionsby | default $defaultOrdersectionsby }}
-      {{- if $isActive }}
-        {{- template "section-print" dict "sect" . "currentnode" $currentNode }}
-        {{- if $pages }}
-          <section>
-        {{- end }}
-      {{- end }}
-      {{- if eq $currentOrdersectionsby "title" }}
-        {{- range $pages.ByTitle }}
-          {{- template "section-tree-print" dict "sect" . "currentnode" $currentNode "isActive" $isActive }}
-        {{- end }}
-      {{- else }}
-        {{- range $pages.ByWeight }}
-          {{- template "section-tree-print" dict "sect" . "currentnode" $currentNode "isActive" $isActive }}
-        {{- end }}
-      {{- end }}
-      {{- if $isActive }}
-        {{- if $pages }}
-          </section>
-        {{- end }}
-      {{- end }}
-    {{- else }}
-      {{- if $isActive }}
-        {{- template "section-print" dict "sect" . "currentnode" $currentNode }}
-      {{- end }}
-    {{- end }}
-  {{- end }}
-{{- end }}
-{{- define "section-print" }}
-  {{- $currentNode := .currentnode }}
-  {{- with .sect }}
-    {{- $currentNode.Page.Store.Set "printHasMathJax" (or ($currentNode.Page.Store.Get "printHasMathJax") (.Page.Store.Get "htmlHasMathJax")) }}
-    {{- $currentNode.Page.Store.Set "printHasMermaid" (or ($currentNode.Page.Store.Get "printHasMermaid") (.Page.Store.Get "htmlHasMermaid")) }}
-    {{- $currentNode.Page.Store.Set "printHasSwagger" (or ($currentNode.Page.Store.Get "printHasSwagger") (.Page.Store.Get "htmlHasSwagger")) }}
-    {{/* if we have a relative link in a print page, our print URL is one level to deep; so we are making it absolute to our page by prepending the page's permalink */}}
-    {{- $link_prefix := strings.TrimRight "/" .Page.RelPermalink }}
-    {{- $content := partial "content.html" . }}
-    {{- $content = replaceRE "((?:src|href)\\s*=(?:\\s*[\"']\\s*)?)(\\.[^\"'\\s>]*|[\\w]+[^\"'\\s>:]*)([\"'\\s>])" (printf "${1}%s/${2}${3}" $link_prefix) $content }}
-    {{- partial "article.html" (dict "page" . "content" $content) }}
-  {{- end }}
-{{- end }}

layouts/partials/footer.html

@@ -7,7 +7,7 @@
     <script src="{{"js/clipboard.min.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}" defer></script>
     <script src="{{"js/perfect-scrollbar.min.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}" defer></script>
     <script src="{{"js/featherlight.min.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}" defer></script>
-{{- $wantsMathJax := or (and (eq (.Scratch.Get "relearnOutputFormat") "HTML") (.Page.Store.Get "htmlHasMathJax")) (and (eq (.Scratch.Get "relearnOutputFormat") "PRINT") (.Page.Store.Get "printHasMathJax")) }}
+{{- $wantsMathJax := or (and (eq (.Scratch.Get "relearnOutputFormat") "HTML") (.Page.Store.Get "selfHasMathJax")) (and (eq (.Scratch.Get "relearnOutputFormat") "PRINT") (.Page.Store.Get "nestedHasMathJax")) }}
 {{- if $wantsMathJax }}
   {{- if isset .Params "mathjaxinitialize" }}
     {{- $.Scratch.Set "mathJaxInitialize" .Params.mathJaxInitialize }}
@@ -48,7 +48,7 @@
     <script id="MathJax-script" async src="{{"js/mathjax/tex-mml-chtml.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}"></script>
   {{- end }}
 {{- end }}
-{{- $wantsMermaid := or (and (eq (.Scratch.Get "relearnOutputFormat") "HTML") (.Page.Store.Get "htmlHasMermaid")) (and (eq (.Scratch.Get "relearnOutputFormat") "PRINT") (.Page.Store.Get "printHasMermaid")) }}
+{{- $wantsMermaid := or (and (eq (.Scratch.Get "relearnOutputFormat") "HTML") (.Page.Store.Get "selfHasMermaid")) (and (eq (.Scratch.Get "relearnOutputFormat") "PRINT") (.Page.Store.Get "nestedHasMermaid")) }}
 {{- if $wantsMermaid }}
     <script src="{{"js/jquery.svg.pan.zoom.js" | relURL}}{{ if not .Site.Params.disableAssetsBusting }}?{{ now.Unix }}{{ end }}" defer></script>
   {{- if isset .Params "custommermaidurl" }}
@@ -78,7 +78,7 @@
       useMermaid( JSON.parse({{ $.Scratch.Get "mermaidInitialize" }}) );
     </script>
 {{- end }}
-{{- $wantsSwagger := or (and (eq (.Scratch.Get "relearnOutputFormat") "HTML") (.Page.Store.Get "htmlHasSwagger")) (and (eq (.Scratch.Get "relearnOutputFormat") "PRINT") (.Page.Store.Get "printHasSwagger")) }}
+{{- $wantsSwagger := or (and (eq (.Scratch.Get "relearnOutputFormat") "HTML") (.Page.Store.Get "selfHasSwagger")) (and (eq (.Scratch.Get "relearnOutputFormat") "PRINT") (.Page.Store.Get "nestedHasSwagger")) }}
 {{- if $wantsSwagger }}
   {{- if isset .Params "customswaggerurl" }}
     <script src="{{ .Params.customSwaggerURL }}" defer></script>

layouts/partials/header.html

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

layouts/partials/initial.html

@@ -1,5 +1,3 @@
-          <article>
-
 <h1>Create this Page</h1>
 <p>
   You need to create a file for this page. You can either
@@ -7,8 +5,4 @@
 <ul>
   <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>
+</ul>
-
-            <footer class="footline">
-          	</footer>
-          </article>

layouts/partials/nestedArticle.html

@@ -0,0 +1,99 @@
+{{- $currentNode := . }}
+{{- $isActive := .IsHome }}
+{{- $isShortcut := false }}
+{{- $r_url := .RelPermalink }}
+{{- with .Site.Menus.shortcuts }}
+  {{- range sort . "Weight" }}
+    {{- $s_url := .URL | relLangURL }}
+    {{- if (eq $s_url $r_url) }}
+      {{- $isShortcut = true }}
+    {{- end }}
+  {{- end }}
+{{- end }}
+{{- $pages := .Site.Home.Sections }}
+{{- $defaultOrdersectionsby := .Site.Params.ordersectionsby | default "weight" }}
+{{- $currentOrdersectionsby := .Site.Home.Params.ordersectionsby | default $defaultOrdersectionsby }}
+{{- if $isShortcut }}
+  {{- template "section-print" dict "sect" . "currentnode" $currentNode }}
+{{- else }}
+  {{- if $isActive }}
+    {{- template "section-print" dict "sect" . "currentnode" $currentNode }}
+    {{- if or $pages }}
+            <section>
+    {{- end }}
+  {{- end }}
+  {{- if eq $currentOrdersectionsby "title" }}
+    {{- range $pages.ByTitle }}
+      {{- template "section-tree-print" dict "sect" . "currentnode" $currentNode "isActive" $isActive }}
+    {{- end }}
+  {{- else }}
+    {{- range $pages.ByWeight }}
+      {{- template "section-tree-print" dict "sect" . "currentnode" $currentNode "isActive" $isActive }}
+    {{- end }}
+  {{- end }}
+  {{- if $isActive }}
+    {{- if $pages }}
+            </section>
+    {{- end }}
+  {{- end }}
+{{- end }}
+{{- define "section-tree-print" }}
+  {{- $currentNode := .currentnode }}
+  {{- $isActive := .isActive }}
+  {{- $currentFileRelPermalink := .currentnode.RelPermalink }}
+  {{- with .sect }}
+    {{- $isSelf := eq .RelPermalink $currentFileRelPermalink }}
+    {{- $isAncestor := and (not $isSelf) (.IsAncestor $currentNode) }}
+    {{- $isActive = or $isSelf $isActive }}
+    {{- $pages := .Pages }}
+    {{- if .Page.IsHome }}
+      {{- $pages = .Sections }}
+    {{- else if .Page.Sections}}
+      {{- $pages = (.Pages | union .Sections) }}
+    {{- end }}
+    {{- $relearnIsHiddenFrom := index ($currentNode.Scratch.Get "relearnIsHiddenFrom") .RelPermalink }}
+    {{- $hidden := and $relearnIsHiddenFrom (not $.showhidden) (not $isSelf) (not $isAncestor) }}
+    {{- if $hidden }}
+    {{- else if or .IsSection .IsHome }}
+      {{- $defaultOrdersectionsby := .Site.Params.ordersectionsby | default "weight" }}
+      {{- $currentOrdersectionsby := .Params.ordersectionsby | default $defaultOrdersectionsby }}
+      {{- if $isActive }}
+        {{- template "section-print" dict "sect" . "currentnode" $currentNode }}
+        {{- if $pages }}
+          <section>
+        {{- end }}
+      {{- end }}
+      {{- if eq $currentOrdersectionsby "title" }}
+        {{- range $pages.ByTitle }}
+          {{- template "section-tree-print" dict "sect" . "currentnode" $currentNode "isActive" $isActive }}
+        {{- end }}
+      {{- else }}
+        {{- range $pages.ByWeight }}
+          {{- template "section-tree-print" dict "sect" . "currentnode" $currentNode "isActive" $isActive }}
+        {{- end }}
+      {{- end }}
+      {{- if $isActive }}
+        {{- if $pages }}
+          </section>
+        {{- end }}
+      {{- end }}
+    {{- else }}
+      {{- if $isActive }}
+        {{- template "section-print" dict "sect" . "currentnode" $currentNode }}
+      {{- end }}
+    {{- end }}
+  {{- end }}
+{{- end }}
+{{- define "section-print" }}
+  {{- $currentNode := .currentnode }}
+  {{- with .sect }}
+    {{- $currentNode.Page.Store.Set "nestedHasMathJax" (or ($currentNode.Page.Store.Get "nestedHasMathJax") (.Page.Store.Get "selfHasMathJax")) }}
+    {{- $currentNode.Page.Store.Set "nestedHasMermaid" (or ($currentNode.Page.Store.Get "nestedHasMermaid") (.Page.Store.Get "selfHasMermaid")) }}
+    {{- $currentNode.Page.Store.Set "nestedHasSwagger" (or ($currentNode.Page.Store.Get "nestedHasSwagger") (.Page.Store.Get "selfHasSwagger")) }}
+    {{/* if we have a relative link in a print page, our print URL is one level to deep; so we are making it absolute to our page by prepending the page's permalink */}}
+    {{- $link_prefix := strings.TrimRight "/" .Page.RelPermalink }}
+    {{- $content := partial "content.html" . }}
+    {{- $content = replaceRE "((?:src|href)\\s*=(?:\\s*[\"']\\s*)?)(\\.[^\"'\\s>]*|[\\w]+[^\"'\\s>:]*)([\"'\\s>])" (printf "${1}%s/${2}${3}" $link_prefix) $content }}
+    {{- partial "output-partial.html" (dict "base" "article" "page" . "parameter" (dict "page" . "content" $content)) }}
+  {{- end }}
+{{- end }}

layouts/partials/output-partial.html

@@ -0,0 +1,10 @@
+{{- $base := .base }}
+{{- $page := .page }}
+{{- $parameter := .parameter }}
+{{- if or (not ($page.Scratch.Get "relearnOutputFormat")) (not (fileExists (printf "/layouts/partials/%s.%s.html" $base (($page.Scratch.Get "relearnOutputFormat") | lower)))) }}
+  {{- if (fileExists (printf "/layouts/partials/%s.html" $base)) }}
+    {{- partial (printf "%s.html" $base) $parameter }}
+  {{- end }}
+{{- else }}
+  {{- partial (printf "%s.%s.html" $base ((.page.Scratch.Get "relearnOutputFormat") | lower)) $parameter }}
+{{- end }}

layouts/partials/page-meta.hugo

@@ -8,15 +8,15 @@
 {{- $currentNode.Scratch.Delete "relearnIsHiddenFrom" }}{{/* the node is hidden from the current page */}}
 {{- $wantsMathjax := or (and (ne $currentNode.Params.disableMathjax nil) (not $currentNode.Params.disableMathjax)) (and (ne .Site.Params.disableMathjax nil) (not .Site.Params.disableMathjax)) }}
 {{- if $wantsMathjax }}
-	{{- $currentNode.Page.Store.Set "htmlHasMathjax" true }}
+	{{- $currentNode.Page.Store.Set "selfHasMathjax" true }}
 {{- end }}
 {{- $wantsMermaid := or (and (ne $currentNode.Params.disableMermaid nil) (not $currentNode.Params.disableMermaid)) (and (ne .Site.Params.disableMermaid nil) (not .Site.Params.disableMermaid)) }}
 {{- if $wantsMermaid }}
-	{{- $currentNode.Page.Store.Set "htmlHasMermaid" true }}
+	{{- $currentNode.Page.Store.Set "selfHasMermaid" true }}
 {{- end }}
 {{- $wantsSwagger := or (and (ne .Params.disableSwagger nil) (not .Params.disableSwagger)) (and (ne .Site.Params.disableSwagger nil) (not .Site.Params.disableSwagger)) }}
 {{- if $wantsSwagger }}
-	{{- $currentNode.Page.Store.Set "htmlHasSwagger" true }}
+	{{- $currentNode.Page.Store.Set "selfHasSwagger" true }}
 {{- end }}
 {{- template "relearn-structure" dict "node" .Site.Home "currentnode" $currentNode "hiddenstem" false "hiddencurrent" false "defaultOrdersectionsby" .Site.Params.ordersectionsby }}
 {{- define "relearn-structure" }}

layouts/partials/shortcodes/math.html

@@ -5,5 +5,5 @@
 <span class="math align-{{ $align }}">
   {{- $content | safeHTML -}}
 </span>
-{{- .Page.Store.Set "htmlHasMathJax" true }}
+{{- .Page.Store.Set "selfHasMathJax" true }}
 {{- end }}

layouts/partials/shortcodes/mermaid.html

@@ -5,5 +5,5 @@
 <div class="mermaid" align="{{ $align }}">
   {{- $content | safeHTML -}}
 </div>
-{{- .Page.Store.Set "htmlHasMermaid" true }}
+{{- .Page.Store.Set "selfHasMermaid" true }}
 {{- end }}

layouts/partials/shortcodes/swagger.html

@@ -24,5 +24,5 @@
   spec-url="{{ $src }}"
   sort-tags="true"
 ></rapi-doc>
-{{- .Page.Store.Set "htmlHasSwagger" true }}
+{{- .Page.Store.Set "selfHasSwagger" true }}
 {{- end }}