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"}
+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.
-+++
-title = "Chapter 1"
-type = "chapter"
-+++
-````
 
-
+## Predefined Designs for the HTML Output Format
-## Predefined Designs
 
 ### 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 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).
 
 A page design usually consists of
 
-- [an archetype file](https://gohugo.io/content-management/archetypes/): a template for creating new Markdown files with this design
+- [one or more content view files](https://gohugo.io/templates/types/#content-view): depending on the output format taken from [the list below](#partials)
-- [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
+- [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
-- CSS styles
+- optional CSS styles
-
-If no `type` is set in your front matter, the page is treated as if `type='default'` was set.
 
 > [!warning]
-> Don't use the `type` option in your modifications for other functionality!
+> Don't use Hugo's reserved `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.
 
 ## 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.
 
-## Creating a Page Designs
+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.
 
-To make a custom page design:
+The Relearn theme ships with the page designs `home`, `chapter`, and `default` for the HTML output format.
 
-1. Choose a name (for example, `mydesign`)
+The shipped `print` and `markdown` output formats only display using the `default` page design.
-2. Create a content view file at `layouts/mydesign/views/article.html`
 
-    ````html {title="layouts/mydesign/views/article.html"}
+## Creating a Page Design
-    <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 "heading-pre.html" . }}{{ partial "heading.html" . }}{{ partial "heading-post.html" . }}
+      <p class="disclaimer">
-    {{ partial "article-content.html" . }}
+        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 {
+    .releasenotes .disclaimer {
-      font-size: 72rem;
-    }
-    .mydesign a {
       background-color: pink;
+      font-size: 72rem;
     }
     </style>
     ````
 
-### Partials
+## Partials
 
-The above example uses `layouts/mydesign/views/article.html` but you have some others
+### For any Output Format
 
-- `layouts/mydesign/baseof.html`: Completely redefine the whole HTML structure, none of the other listed partials will be used
+These files are common for all output formats.
-- `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/<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
-- `layouts/mydesign/views/article.html`: Controls how one page's content and title are displayed
+
+### 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
+
+For a real-world example, check out the `changelog` page design implementation
+
+- [`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`
+## Creating an Output Format
-2. Implement all the necessary code in this file
 
-## 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
+1. Add the output format to your `hugo.toml`
-- `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
 
-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
 +++

exampleSite/content/introduction/releasenotes/7/0.en.md

@@ -27,26 +27,24 @@ weight = -0
 
   Specifically, you will have to adapt your site if you have
 
-  - [overwritten the `header.html`, `menu.html` or `footer.html` partials](configuration/customization/partials)
   - [self-defined output formats](configuration/customization/outputformats)
-  - self-defined archetype partials in `layouts/partials/archetypes` - now becoming [page designs](configuration/customization/designs)
+  - self-defined archetypes - now becoming [page designs](configuration/customization/designs) and using [Hugo's content view](https://gohugo.io/templates/types/#content-view) mechanism
+  - [overwritten the `header.html`, `menu.html` or `footer.html` partials](configuration/customization/partials) - needs sync with implementation changes
   - [overwritten prev/next topbar buttons](configuration/customization/topbar) - needs sync with implementation changes
 
 - {{% badge style="warning" title=" " %}}Breaking{{% /badge %}} This release changes the way the search index and the dedicated search page are generated. This may require reconfiguration by you to still work as you have intended.
 
-  You need to remove the now obsolete `search` and `searchpage` output format from `[outputs.home]` in your `hugo.toml`, resulting in something similar to
+  Remove the now obsolete `search` and `searchpage` output format from `[outputs.home]` in your `hugo.toml`, resulting in something similar to
 
 	{{< multiconfig file=hugo >}}
 	[outputs]
 	  home = ['html', 'rss', 'print']
 	{{< /multiconfig >}}
 
-  After that, your build will succeed but will most likely cause new defaults to be applied. With no further settings, in-page search, search popup and dedicated search page are all active by default. This can be reconfigured.
+  After that, your build will succeed but will may cause new defaults to be applied. With no further settings, in-page search, search popup and dedicated search page are all active by default. [This can be reconfigured](configuration/sidebar/search#configure-search).
 
   In addition, you are now able to overwrite the default file name of the search index and the default page name of the dedicated search page by changing `searchIndexURL` and `searchPageURL` respectively in your `hugo.toml`.
 
-  See the [updated documentation](configuration/sidebar/search) for reference.
-
 ### Change
 
 - {{% badge style="note" title=" " %}}Change{{% /badge %}} Once again, the theme changed the font. We switched to the excellent [Roboto Flex](https://github.com/googlefonts/roboto-flex) font.

exampleSite/content/introduction/releasenotes/7/3.en.md

@@ -15,3 +15,5 @@ weight = -3
 - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The topbar button for the print format [can now be hidden](authoring/frontmatter/topbar/#print-button) if the print output format is active by setting `disablePrintButton=true` in your `hugo.toml` or Front Matter.
 
 - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The theme supports the new [`markdown` output format](configuration/sitemanagement/outputformats/#markdown-support) which behaves similar in configuration as the `print` output format but allows the original Markdown source of a page to be viewed.
+
+  You can see this in action on the above linked page, accessible by clikcking the topbar button.

layouts/partials/version.txt

@@ -1 +1 @@
-7.2.1+780744552727654e03983918f0ad49ccae2a696b
+7.2.1+fbec3905ed0a2578c4a8763c90d9fe58909004fe