From 2e198810a95fdbff698c2180edd4e14a4fabab0f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6ren=20Weber?= Date: Tue, 31 Dec 2024 18:02:57 +0100 Subject: [PATCH] docs: improve docs and examples for output formats and page design #980 todo: migration hints --- .../frontmatter/designs/_index.en.md | 27 ++-- .../authoring/frontmatter/topbar/_index.en.md | 1 + .../frontmatter/topbar/_index.pir.md | 1 + .../customization/designs/index.en.md | 93 ++++++++------ .../customization/outputformats/_index.en.md | 119 ++++++++++++++++-- .../customization/topbar/_index.en.md | 1 + .../customization/topbar/_index.pir.md | 1 + .../sitemanagement/outputformats/_index.en.md | 9 +- .../outputformats/_index.pir.md | 3 +- .../introduction/releasenotes/7/0.en.md | 10 +- .../introduction/releasenotes/7/3.en.md | 2 + layouts/partials/version.txt | 2 +- 12 files changed, 198 insertions(+), 71 deletions(-) diff --git a/exampleSite/content/authoring/frontmatter/designs/_index.en.md b/exampleSite/content/authoring/frontmatter/designs/_index.en.md index e403df1acc..0b3ee7e37f 100644 --- a/exampleSite/content/authoring/frontmatter/designs/_index.en.md +++ b/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} diff --git a/exampleSite/content/authoring/frontmatter/topbar/_index.en.md b/exampleSite/content/authoring/frontmatter/topbar/_index.en.md index 7e0a7cfa33..917100cc8c 100644 --- a/exampleSite/content/authoring/frontmatter/topbar/_index.en.md +++ b/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 +++ diff --git a/exampleSite/content/authoring/frontmatter/topbar/_index.pir.md b/exampleSite/content/authoring/frontmatter/topbar/_index.pir.md index ef5da03e54..8066855120 100644 --- a/exampleSite/content/authoring/frontmatter/topbar/_index.pir.md +++ b/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 +++ diff --git a/exampleSite/content/configuration/customization/designs/index.en.md b/exampleSite/content/configuration/customization/designs/index.en.md index 8c17ccf84c..6e14b122a5 100644 --- a/exampleSite/content/configuration/customization/designs/index.en.md +++ b/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 -- [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 - -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. -## 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`) -2. Create a content view file at `layouts/mydesign/views/article.html` +The shipped `print` and `markdown` output formats only display using the `default` page design. - ````html {title="layouts/mydesign/views/article.html"} -
+## Creating a Page Design + +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"} +
- {{ partial "content-header.html" . }} + {{partial "content-header.html" .}}
-
AWESOME
- {{ 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" .}} +

+ This software release comes without any warranty! +

+ {{partial "article-content.html" .}}
- {{ partial "content-footer.html" . }} + {{partial "content-footer.html" .}}
```` - 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"} ```` -### 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 -- `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 +These files are common for all output formats. + +- `layouts//baseof.`: _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//views/article.html`: _Optional_: Controls how one page's content and title are displayed +- `layouts//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//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) diff --git a/exampleSite/content/configuration/customization/outputformats/_index.en.md b/exampleSite/content/configuration/customization/outputformats/_index.en.md index 23988ec7e5..28de419a99 100644 --- a/exampleSite/content/configuration/customization/outputformats/_index.en.md +++ b/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"} + + + + {{ .Title }} + + + + +
+ {{- block "body" . }}{{ end }} +
+ + + ```` + + 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"} + + ```` + +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 }} + + {{- 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..html`: _Optional_: Controls how a page's content and title are displayed +- `layouts/_default/views/body..html`: _Optional_: Determines the page body structure +- `layouts/_default/views/menu..html`: _Optional_: Defines the sidebar menu layout +- `layouts/_default/views/storeOutputFormat..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.`: _Mandatory_: Controls how sections are displayed +- `layouts/_default/single.`: _Mandatory_: Controls how pages are displayed +- `layouts/_default/baseof.`: _Optional_: Controls how sections and pages are displayed. If not provided, you have to provide your implementation in `list.` and `single.` + +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) diff --git a/exampleSite/content/configuration/customization/topbar/_index.en.md b/exampleSite/content/configuration/customization/topbar/_index.en.md index cf726de629..d822516246 100644 --- a/exampleSite/content/configuration/customization/topbar/_index.en.md +++ b/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 +++ diff --git a/exampleSite/content/configuration/customization/topbar/_index.pir.md b/exampleSite/content/configuration/customization/topbar/_index.pir.md index bc06e38c9e..051ff64232 100644 --- a/exampleSite/content/configuration/customization/topbar/_index.pir.md +++ b/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 +++ diff --git a/exampleSite/content/configuration/sitemanagement/outputformats/_index.en.md b/exampleSite/content/configuration/sitemanagement/outputformats/_index.en.md index caf89646a8..cf78eac879 100644 --- a/exampleSite/content/configuration/sitemanagement/outputformats/_index.en.md +++ b/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`: diff --git a/exampleSite/content/configuration/sitemanagement/outputformats/_index.pir.md b/exampleSite/content/configuration/sitemanagement/outputformats/_index.pir.md index b7815b09da..c2e31307d5 100644 --- a/exampleSite/content/configuration/sitemanagement/outputformats/_index.pir.md +++ b/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 +++ diff --git a/exampleSite/content/introduction/releasenotes/7/0.en.md b/exampleSite/content/introduction/releasenotes/7/0.en.md index 7d508a9359..0e5856b2ff 100644 --- a/exampleSite/content/introduction/releasenotes/7/0.en.md +++ b/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. diff --git a/exampleSite/content/introduction/releasenotes/7/3.en.md b/exampleSite/content/introduction/releasenotes/7/3.en.md index 9197df19a9..c1ba8c73ca 100644 --- a/exampleSite/content/introduction/releasenotes/7/3.en.md +++ b/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. diff --git a/layouts/partials/version.txt b/layouts/partials/version.txt index cef9a23a1d..c7a3f50f95 100644 --- a/layouts/partials/version.txt +++ b/layouts/partials/version.txt @@ -1 +1 @@ -7.2.1+780744552727654e03983918f0ad49ccae2a696b \ No newline at end of file +7.2.1+fbec3905ed0a2578c4a8763c90d9fe58909004fe \ No newline at end of file