docs: improve docs and examples for output formats and page design #980

todo: migration hints

exampleSite/content/authoring/frontmatter/designs/_index.en.md

@@ -5,9 +5,13 @@ title = "Page Designs"
 weight = 1
 +++
 
-A page is displayed by exactly one page design and represented by [Hugo's reserved `type` front matter](https://gohugo.io/content-management/front-matter/#type).
+Page designs are used to provide different layouts for your pages.
 
-The Relearn theme offers the page designs `home`, `chapter`, and `default` but you can [define further custom page designs](configuration/customization/designs).
+A page is displayed by exactly one page design and is represented by [Hugo's reserved `type` front matter](https://gohugo.io/content-management/front-matter/#type).
+
+The Relearn theme ships with the page designs `home`, `chapter`, and `default` for the HTML output format but you can [define further custom page designs](configuration/customization/designs).
+
+## Using a Page Design
 
 Regardless of shipped or custom page design, you are using them in the same way.
 
@@ -17,19 +21,18 @@ Regardless of shipped or custom page design, you are using them in the same way.
 	hugo new --kind chapter chapter1/_index.md
     ````
 
-- If you are creating your Markdown files manually, you can achieve the same by just setting `type='chapter'` in the front matter.
+- If you are creating your Markdown files manually, you can achieve the same by just setting `type='chapter'` in the front matter to make your page displayed with the `chapter` page design.
 
-Your resulting Markdown file needs to have at least the `type` front matter set to the value of the page design
-
-````toml {title="_index.md"}
-+++
-title = "Chapter 1"
-type = "chapter"
-+++
-````
+    ````toml {title="_index.md"}
+    +++
+    title = "Chapter 1"
+    type = "chapter"
+    +++
+    ````
 
+If no `type` is set in your front matter or the page design doesn't exist for a given output format, the page is treated as if `type='default'` was set.
 
-## Predefined Designs
+## Predefined Designs for the HTML Output Format
 
 ### Home {#archetypes-home}
 

exampleSite/content/authoring/frontmatter/topbar/_index.en.md

@@ -3,6 +3,7 @@ categories = ["howto"]
 description = "Configure the topbar"
 frontmatter = ["disableBreadcrumb", "disableNextPrev", "disableMarkdownButton", "disablePrintButton", "disableToc", "editURL"]
 options = ["disableBreadcrumb", "disableNextPrev", "disableMarkdownButton", "disablePrintButton", "disableToc", "editURL"]
+outputs = ["html", "rss", "print", "markdown"]
 title = "Topbar"
 weight = 4
 +++

exampleSite/content/authoring/frontmatter/topbar/_index.pir.md

@@ -3,6 +3,7 @@ categories = ["howto"]
 description = "Configure the topbar"
 frontmatter = ["disableBreadcrumb", "disableNextPrev", "disableMarkdownButton", "disablePrintButton", "disableToc", "editURL"]
 options = ["disableBreadcrumb", "disableNextPrev", "disableMarkdownButton", "disablePrintButton", "disableToc", "editURL"]
+outputs = ["html", "rss", "print", "markdown"]
 title = "Topbarrr"
 weight = 4
 +++

exampleSite/content/configuration/customization/designs/index.en.md

@@ -5,80 +5,97 @@ title = "Page Designs"
 weight = 5
 +++
 
-A page is displayed by exactly one page design. The Relearn theme offers the page designs `home`, `chapter`, and `default`.
+Page designs are used to provide different layouts for a given output format. If you instead want to [provide a new output format](configuration/customization/outputformats), the theme got you covered as well.
 
-A page design usually consists of
+A page is displayed by exactly one page design _for each output format_, is represented by [Hugo's reserved `type` front matter](https://gohugo.io/content-management/front-matter/#type) and uses [Hugo's content view mechanism](https://gohugo.io/templates/types/#content-view).
 
-- [an archetype file](https://gohugo.io/content-management/archetypes/): a template for creating new Markdown files with this design
-- [content view files](https://gohugo.io/templates/types/#content-view): represented by [Hugo's reserved `type` front matter](https://gohugo.io/content-management/front-matter/#type) and backed by matching partials
-- CSS styles
+A page design usually consists of
 
-If no `type` is set in your front matter, the page is treated as if `type='default'` was set.
+- [one or more content view files](https://gohugo.io/templates/types/#content-view): depending on the output format taken from [the list below](#partials)
+- [an optional archetype file](https://gohugo.io/content-management/archetypes/): a template for creating new Markdown files with the correct setting for the `type` front matter and any furhter parameter
+- optional CSS styles
 
 > [!warning]
-> Don't use the `type` option in your modifications for other functionality!
-
-All shipped designs use the theme's framework from `themes/hugo-theme-learn/layouts/_default/baseof.html`, containing of the same topbar and sidebar but can change how content appears in the center of the page.
+> Don't use Hugo's reserved `type` option in your modifications for other functionality!
 
 ## Using a Page Design
 
-Regardless of shipped or custom page design, you are [using them](authoring/frontmatter/designs) in the same way.
+Regardless of shipped or custom page designs, you are [using them in the same way](authoring/frontmatter/designs). Either by manually setting the `type` front matter to the value of the page design or by using an archetype during creation of a new page.
+
+If no `type` is set in your front matter or the page design doesn't exist for a given output format, the page is treated as if `type='default'` was set.
 
-## Creating a Page Designs
+The Relearn theme ships with the page designs `home`, `chapter`, and `default` for the HTML output format.
 
-To make a custom page design:
+The shipped `print` and `markdown` output formats only display using the `default` page design.
 
-1. Choose a name (for example, `mydesign`)
-2. Create a content view file at `layouts/mydesign/views/article.html`
+## Creating a Page Design
 
-    ````html {title="layouts/mydesign/views/article.html"}
-    <article class="mydesign">
+Suppose you are writing a documentation site for some software. Each time a new release is created, you are adding a new releasenotes page to your site. Those pages should contain a common disclaimer at the top. You neither want to copy the text into each new file nor want you to use a shortcode but create a page design called `releasenotes`.
+
+1. Choose a name (here, `releasenotes`)
+2. Create a content view file at `layouts/releasenotes/views/article.html`
+
+    ````html {title="layouts/releasenotes/views/article.html" hl_Lines="6-8"}
+    <article class="releasenotes">
       <header class="headline">
-    {{ partial "content-header.html" . }}
+        {{partial "content-header.html" .}}
       </header>
-    <div class="article-subheading">AWESOME</div>
-    {{ partial "heading-pre.html" . }}{{ partial "heading.html" . }}{{ partial "heading-post.html" . }}
-    {{ partial "article-content.html" . }}
+      {{partial "heading-pre.html" .}}{{partial "heading.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" . }}
+        {{partial "content-footer.html" .}}
       </footer>
     </article>
     ````
 
-    In this file, you can customize the page design as needed. Typically, you'll want to:
+    The marked lines are your customizations, the rest of the file was copied over from the default implementation of [`layouts/_default/views/article.html`](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/_default/views/article.html)
+
+    In this file, you can customize the page structure as needed. For HTML based output formats, typically you'll want to:
 
     - Set a `class` at the `article` element for custom CSS styles
-    - Use `{{ partial "article-content.html" . }}` to show your page content
+    - Call `{{ partial "article-content.html" . }}` to show your page content
 
-3. Create an archetype file at `archetypes/mydesign.md` (optional)
+3. _Optional_: create an archetype file at `archetypes/releasenotes.md`
 
-    ````html {title="archetypes/mydesign.md"}
+    ````toml {title="archetypes/releasenotes.md"}
     +++
     title = "{{ replace .Name "-" " " | title }}"
-    type = "mydesign"
+    type = "releasenotes"
     +++
 
-    This is my new design.
+    This is a new releasenote.
     ````
 
-4. Add CSS in file `layouts/partials/custom-header.html` (optional)
+4. _Optional_: add CSS in the file `layouts/partials/custom-header.html`
 
     ````html {title="layouts/partials/custom-header.html"}
     <style>
-    .mydesign .article-subheading {
-      font-size: 72rem;
-    }
-    .mydesign a {
+    .releasenotes .disclaimer {
       background-color: pink;
+      font-size: 72rem;
     }
     </style>
     ````
 
-### Partials
+## Partials
+
+### For any Output Format
+
+These files are common for all output formats.
+
+- `layouts/<DESIGN>/baseof.<FORMAT>`: _Optional_: The top most file you could provide to completely redefine the whole design. No further partials will be called if you don' call them yourself
+
+### For HTML Output Formats
+
+If you want to keep the general HTML framework and only change specific parts, you can provide these files for the page desingn for the HTML output format independently of one another.
+
+- `layouts/<DESIGN>/views/article.html`: _Optional_: Controls how one page's content and title are displayed
+- `layouts/<DESIGN>/views/body.html`: _Optional_: Determines what to contain in the content area (for example a single page, a list of pages, a tree of sub pages)
+- `layouts/<DESIGN>/views/menu.html`: _Optional_: Defines the sidebar menu layout
 
-The above example uses `layouts/mydesign/views/article.html` but you have some others
+For a real-world example, check out the `changelog` page design implementation
 
-- `layouts/mydesign/baseof.html`: Completely redefine the whole HTML structure, none of the other listed partials will be used
-- `layouts/mydesign/views/menu.html`: Defines the sidebar menu layout
-- `layouts/mydesign/views/body.html`: Determines what to contain in the content area (for example a single page, a list of pages, a tree of sub pages)
-- `layouts/mydesign/views/article.html`: Controls how one page's content and title are displayed
+- [`exampleSite/layouts/changelog/views/article.html`](https://github.com/McShelby/hugo-theme-relearn/blob/main/exampleSite/layouts/changelog/views/article.html)

exampleSite/content/configuration/customization/outputformats/_index.en.md

@@ -3,28 +3,123 @@ categories = ["explanation", "howto"]
 description = "Adding Custom Output Formats"
 title = "Output Formats"
 weight = 6
+disableToc = false
 +++
 
-In addition to the [output formats coming with the theme](configuration/sitemanagement/outputformats), you can create your own [output formats](https://gohugo.io/templates/output-formats/).
+Hugo can display your content in different [formats](https://gohugo.io/templates/output-formats/) like HTML, JSON, Google AMP, etc. To do this, templates must be provided.
 
-## Starting from Scratch
+The Relearn theme by default comes with templates for [HTML, HTML for print, RSS and Markdown](configuration/sitemanagement/outputformats). If this is not enough, this page describes how you can create your own output formats.
 
-If you want to add a new output format called `myformat` that outputs HTML and you want to build everything yourself without using the theme's components:
+If you instead just want to [customize the layout of an existing output format](configuration/customization/designs), the theme got you covered as well.
 
-1. Create a file `layouts/_default/baseof.myformat.html`
-2. Implement all the necessary code in this file
+## Creating an Output Format
 
-## Using the Theme's Structure
+Suppose you want to be able to send your articles as HTML formatted emails. The pages of these format need to be self contained so an email client can display the content without loading any further assets.
 
-If you want to keep the general framework and only change specific parts, you can override these files:
+Therefore we add a new output format called `email` that outputs HTML and assembles a completely custom HTML document structure.
 
-- `layouts/_default/views/article.html`: Controls how a page's content and title are displayed
-- `layouts/_default/views/body.html`: Determines the page body structure
-- `layouts/_default/views/menu.html`: Defines the sidebar menu layout
-- `layouts/_default/views/storeOutputFormat.html`: Stores the output format name for use in the framework
+1. Add the output format to your `hugo.toml`
 
-For a real-world example, check out the `print` output format implementations
+    {{< multiconfig file=hugo >}}
+    [outputFormats]
+      [outputFormats.email]
+        name= "email"
+        baseName = "index.email"
+        isHTML = true
+        mediaType = 'text/html'
+        permalinkable = false
+        noUgly = true
+
+    [outputs]
+      home = ["html", "rss", "email"]
+      section = ["html", "rss", "email"]
+      page = ["html", "rss", "email"]
+    {{< /multiconfig >}}
+
+2. Create a file `layouts/_default/baseof.email.html`
+
+    ````html {title="layouts/_default/baseof.email.html" hl_Lines="15"}
+    <!DOCTYPE html>
+    <html>
+    <head>
+      <title>{{ .Title }}</title>
+      <style type="text/css">
+        /* add some styles here to make it pretty */
+      </style>
+      <style type="text/css">
+        /* add chroma style for code highlighting */
+        {{- "/assets/css/chroma-relearn-light.css" | readFile | safeCSS }}
+      </style>
+    </head>
+    <body>
+      <main>
+        {{- block "body" . }}{{ end }}
+      </main>
+    </body>
+    </html>
+    ````
+
+    The marked `block` construct above will cause the display of the article with a default HTML structure. 	In case you want to keep it really simple, you could replace this line with just `{{ .Content }}`.
+
+3. _Optional_: create a file `layouts/_default/views/article.email.html`
+
+	In our case, we want to display a disclaimer in front of every article. To do this we have to define the output of an article ourself and rely on the above `block` statement to call our template.
+
+    ````html {title="layouts/_default/views/article.email.html"}
+    <article class="email">
+      <blockquote>
+        View this article on <a href="http://example.com{{ .RelPermalink }}">our website</a>
+      </blockquote>
+      {{ partial "article-content.html" . }}
+    </article>
+    ````
+
+4. _Optional_: create a file `layouts/_default/_markup_/render-image.email.html`
+
+    In our case, we want to convert each image into a base 64 encoded string to display it inline in the email without loading external assets.
+
+    ````html {title="layouts/_default/_markup_/render-image.email.html"}
+    {{- $dest_url := urls.Parse .Destination }}
+    {{- $dest_path := path.Clean ($dest_url.Path) }}
+    {{- $img := .Page.Resources.GetMatch $dest_path }}
+    {{- if and (not $img) .Page.File }}
+      {{- $path := path.Join .Page.File.Dir $dest_path }}
+      {{- $img = resources.Get $path }}
+    {{- end }}
+    {{- if $img }}
+      {{- if (gt (len $img.Content) 1000000000) }}
+        {{/* currently resizing does not work for animated gifs :-( */}}
+        {{- $img = $img.Resize "600x webp q75" }}
+      {{- end }}
+      <img src="data:{{ $img.MediaType }};base64,{{ $img.Content | base64Encode }}">
+    {{- end }}
+    ````
+
+## Partials
+
+### For HTML Output Formats
+
+If you want to keep the general HTML framework and only change specific parts, you can provide these files for your output format independently of one another:
+
+- `layouts/_default/views/article.<FORMAT>.html`: _Optional_: Controls how a page's content and title are displayed
+- `layouts/_default/views/body.<FORMAT>.html`: _Optional_: Determines the page body structure
+- `layouts/_default/views/menu.<FORMAT>.html`: _Optional_: Defines the sidebar menu layout
+- `layouts/_default/views/storeOutputFormat.<FORMAT>.html`: _Optional_: Stores the output format name for use in the framework to let the body element been marked with an output format specific class
+
+For a real-world example, check out the `print` output format implementation
 
 - [`layouts/_default/views/body.print.html`](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/_default/views/body.print.html)
 - [`layouts/_default/views/menu.print.html`](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/_default/views/menu.print.html)
 - [`layouts/_default/views/storeOutputFormat.print.html`](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/_default/views/storeOutputFormat.print.html)
+
+### For Non-HTML Output Formats
+
+- `layouts/_default/list.<FORMAT>`: _Mandatory_: Controls how sections are displayed
+- `layouts/_default/single.<FORMAT>`: _Mandatory_: Controls how pages are displayed
+- `layouts/_default/baseof.<FORMAT>`: _Optional_: Controls how sections and pages are displayed. If not provided, you have to provide your implementation in `list.<FORMAT>` and `single.<FORMAT>`
+
+For a real-world example, check out the `markdown` output format implementation
+
+- [`layouts/_default/baseof.md`](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/_default/baseof.md)
+- [`layouts/_default/list.md`](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/_default/list.md)
+- [`layouts/_default/single.md`](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/_default/single.md)

exampleSite/content/configuration/customization/topbar/_index.en.md

@@ -2,6 +2,7 @@
 categories = ["explanation", "reference"]
 description = "How to extend the topbar"
 options = ["editURL"]
+outputs = ["html", "rss", "print", "markdown"]
 title = "Topbar"
 weight = 4
 +++

exampleSite/content/configuration/customization/topbar/_index.pir.md

@@ -2,6 +2,7 @@
 categories = ["explanation", "reference"]
 description = "How to extend the topbar"
 options = ["editURL"]
+outputs = ["html", "rss", "print", "markdown"]
 title = "Topbarrr"
 weight = 4
 +++

exampleSite/content/configuration/sitemanagement/outputformats/_index.en.md

@@ -1,10 +1,17 @@
 +++
 categories = ["howto"]
-description = "What other formats can a page be displayed in"
+description = "What formats can a page be displayed in"
+outputs = ["html", "rss", "print", "markdown"]
 title = "Available Output Formats"
 weight = 5
 +++
 
+The Relearn theme by default comes with templates for HTML and RSS for each page.
+
+In addition you can configure the below formats.
+
+If this is not enough, learn how to [create your own output formats](configuration/customization/outputformats).
+
 ## Print Support
 
 Enable print support to print entire chapters or the whole site. Add the `print` output format to your home, section, and page in `hugo.toml`:

exampleSite/content/configuration/sitemanagement/outputformats/_index.pir.md

@@ -1,6 +1,7 @@
 +++
 categories = ["howto"]
-description = "What other formats can a page be displayed in"
+description = "What formats can a page be displayed in"
+outputs = ["html", "rss", "print", "markdown"]
 title = "Available Output Formats"
 weight = 5
 +++