From 6747b8862e1ea7331662a6376ef02a48126816ae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6ren=20Weber?= Date: Tue, 31 Dec 2024 20:50:15 +0100 Subject: [PATCH] docs: improve migration instructions for output formats and page design #980 --- .../customization/designs/index.en.md | 47 ++++++++ .../customization/outputformats/_index.en.md | 106 +++++++++++++++++- .../introduction/releasenotes/7/0.en.md | 4 +- layouts/partials/version.txt | 2 +- 4 files changed, 155 insertions(+), 4 deletions(-) diff --git a/exampleSite/content/configuration/customization/designs/index.en.md b/exampleSite/content/configuration/customization/designs/index.en.md index 6e14b122a5..20a6af30b8 100644 --- a/exampleSite/content/configuration/customization/designs/index.en.md +++ b/exampleSite/content/configuration/customization/designs/index.en.md @@ -99,3 +99,50 @@ If you want to keep the general HTML framework and only change specific parts, y 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) + +## Migration to Relearn 7 or higher + +Previous to Relearn 7, page designs were defined by a proprietary solution unique to the theme. Depending on your modifications you may have to change some or all of the following to migrate to Relearn 7's page designs. + +- In all your `*.md` files, replace the `archetype` front matter with `type`; the value stays the same; don't forget your archetype files if you have some +- Move your files `layouts/partials/archetypes//article.html` to `layouts//views/article.html` + + The files will most likely require further modifications as they now receive the page as it context (dot `.`) instead of the `.page` and `.content` parameter. + + **Old**: + + ````html {title="layouts/partials/archetypes/<DESIGN>/article.html" hl_Lines="1-3 10 16"} + {{- $page := .page }} + {{- $content := .content }} + {{- with $page }} +
+
+ {{- partial "content-header.html" . }} +
+ {{partial "heading-pre.html" .}}{{partial "heading.html" .}}{{partial "heading-post.html" .}} + + {{ $content | safeHTML }} + +
+ {{- partial "content-footer.html" . }} +
+
+ {{- end }} + ```` + + **New**: + + ````html {title="layouts/<DESIGN>/views/article.html" hl_Lines="7"} +
+
+ {{- partial "content-header.html" . }} +
+ {{partial "heading-pre.html" .}}{{partial "heading.html" .}}{{partial "heading-post.html" .}} + + {{ partial "article-content.html" . }} + +
+ {{- partial "content-footer.html" . }} +
+
+ ```` diff --git a/exampleSite/content/configuration/customization/outputformats/_index.en.md b/exampleSite/content/configuration/customization/outputformats/_index.en.md index 28de419a99..9edaee834b 100644 --- a/exampleSite/content/configuration/customization/outputformats/_index.en.md +++ b/exampleSite/content/configuration/customization/outputformats/_index.en.md @@ -102,7 +102,7 @@ Therefore we add a new output format called `email` that outputs HTML and assemb 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/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/_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 @@ -123,3 +123,107 @@ 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) + +## Migration to Relearn 7 or higher + +Previous to Relearn 7, HTML output formats did not use the `baseof.html` but now do. + +### For HTML Output Formats + +- Move your files `layouts/partials/article..html` to `layouts/_default/views/article..html` + + The files will most likely require further modifications as they now receive the page as it context (dot `.`) instead of the `.page` and `.content` parameter. + + **Old**: + + ````html {title="layouts/partials/article.<FORMAT>.html" hl_Lines="1-3 10 16"} + {{- $page := .page }} + {{- $content := .content }} + {{- with $page }} +
+
+ {{- partial "content-header.html" . }} +
+ {{partial "heading-pre.html" .}}{{partial "heading.html" .}}{{partial "heading-post.html" .}} + + {{ $content | safeHTML }} + +
+ {{- partial "content-footer.html" . }} +
+
+ {{- end }} + ```` + + **New**: + + ````html {title="layouts/_default/views/article.<FORMAT>.html" hl_Lines="7"} +
+
+ {{- partial "content-header.html" . }} +
+ {{partial "heading-pre.html" .}}{{partial "heading.html" .}}{{partial "heading-post.html" .}} + + {{ partial "article-content.html" . }} + +
+ {{- partial "content-footer.html" . }} +
+
+ ```` + +### For Non-HTML Output Formats + +- Merge your files `layouts/partials/header..html`, `layouts/partials/footer..html` to `layouts/_default/baseof..html` + + **Old**: + + ````html {title="layouts/partials/header.<FORMAT>.html"} + + + + {{ .Title }} + + + + +
+ ```` + + ````html {title="layouts/partials/footer.<FORMAT>.html"} +
+ + + ```` + + **New**: + + The upper part of the file is from your `header..html` and the lower part is from your `footer..html`. + + The marked line needs to be added, so your output format uses a potential `layouts/_default/views/article..html` + + ````html {title="layouts/_default/baseof.<FORMAT>.html" hl_Lines="15"} + + + + {{ .Title }} + + + + +
+ {{- block "body" . }}{{ end }} +
+ + + ```` diff --git a/exampleSite/content/introduction/releasenotes/7/0.en.md b/exampleSite/content/introduction/releasenotes/7/0.en.md index 0e5856b2ff..fd98cf57fb 100644 --- a/exampleSite/content/introduction/releasenotes/7/0.en.md +++ b/exampleSite/content/introduction/releasenotes/7/0.en.md @@ -27,8 +27,8 @@ weight = -0 Specifically, you will have to adapt your site if you have - - [self-defined output formats](configuration/customization/outputformats) - - self-defined archetypes - now becoming [page designs](configuration/customization/designs) and using [Hugo's content view](https://gohugo.io/templates/types/#content-view) mechanism + - [self-defined output formats](configuration/customization/outputformats#migration-to-relearn-7-or-higher) + - self-defined archetypes - now becoming [page designs](configuration/customization/designs#migration-to-relearn-7-or-higher) 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 diff --git a/layouts/partials/version.txt b/layouts/partials/version.txt index c7a3f50f95..10cb3eeb4e 100644 --- a/layouts/partials/version.txt +++ b/layouts/partials/version.txt @@ -1 +1 @@ -7.2.1+fbec3905ed0a2578c4a8763c90d9fe58909004fe \ No newline at end of file +7.2.1+2e198810a95fdbff698c2180edd4e14a4fabab0f \ No newline at end of file