nishiki/hugo-theme-relearn
1
0
Fork 0
mirror of https://github.com/McShelby/hugo-theme-relearn.git synced 2025-01-18 02:40:24 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: improve migration instructions for output formats and page design #980
Some checks failed
docs-build-deployment / Run deploy (push) Has been cancelled
Details
docs-build / Run build (push) Has been cancelled
Details

Browse source
This commit is contained in:
Sören Weber 2024-12-31 20:50:15 +01:00
parent 2e198810a9
commit 6747b8862e
No known key found for this signature in database
GPG key ID: BEC6D55545451B6D
4 changed files with 155 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

47
exampleSite/content/configuration/customization/designs/index.en.md
View file

@ -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/<DESIGN>/article.html` to `layouts/<DESIGN>/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/&lt;DESIGN&gt;/article.html" hl_Lines="1-3 10 16"}
{{- $page := .page }}
{{- $content := .content }}
{{- with $page }}
<article class="default">
<header class="headline">
{{- partial "content-header.html" . }}
</header>
{{partial "heading-pre.html" .}}{{partial "heading.html" .}}{{partial "heading-post.html" .}}
{{ $content | safeHTML }}
<footer class="footline">
{{- partial "content-footer.html" . }}
</footer>
</article>
{{- end }}
````
**New**:
````html {title="layouts/&lt;DESIGN&gt;/views/article.html" hl_Lines="7"}
<article class="default">
<header class="headline">
{{- partial "content-header.html" . }}
</header>
{{partial "heading-pre.html" .}}{{partial "heading.html" .}}{{partial "heading-post.html" .}}
{{ partial "article-content.html" . }}
<footer class="footline">
{{- partial "content-footer.html" . }}
</footer>
</article>
````

106
exampleSite/content/configuration/customization/outputformats/_index.en.md
View file

@ -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.<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/body.<FORMAT>.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.<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
@ -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.<FORMAT>.html` to `layouts/_default/views/article.<FORMAT>.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.&lt;FORMAT&gt;.html" hl_Lines="1-3 10 16"}
{{- $page := .page }}
{{- $content := .content }}
{{- with $page }}
<article class="default">
<header class="headline">
{{- partial "content-header.html" . }}
</header>
{{partial "heading-pre.html" .}}{{partial "heading.html" .}}{{partial "heading-post.html" .}}
{{ $content | safeHTML }}
<footer class="footline">
{{- partial "content-footer.html" . }}
</footer>
</article>
{{- end }}
````
**New**:
````html {title="layouts/_default/views/article.&lt;FORMAT&gt;.html" hl_Lines="7"}
<article class="default">
<header class="headline">
{{- partial "content-header.html" . }}
</header>
{{partial "heading-pre.html" .}}{{partial "heading.html" .}}{{partial "heading-post.html" .}}
{{ partial "article-content.html" . }}
<footer class="footline">
{{- partial "content-footer.html" . }}
</footer>
</article>
````
### For Non-HTML Output Formats
- Merge your files `layouts/partials/header.<FORMAT>.html`, `layouts/partials/footer.<FORMAT>.html` to `layouts/_default/baseof.<FORMAT>.html`
**Old**:
````html {title="layouts/partials/header.&lt;FORMAT&gt;.html"}
<!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>
````
````html {title="layouts/partials/footer.&lt;FORMAT&gt;.html"}
</main>
</body>
</html>
````
**New**:
The upper part of the file is from your `header.<FORMAT>.html` and the lower part is from your `footer.<FORMAT>.html`.
The marked line needs to be added, so your output format uses a potential `layouts/_default/views/article.<FORMAT>.html`
````html {title="layouts/_default/baseof.&lt;FORMAT&gt;.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>
````

4
exampleSite/content/introduction/releasenotes/7/0.en.md
View file

@ -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

2
layouts/partials/version.txt
View file

@ -1 +1 @@
7.2.1+fbec3905ed0a2578c4a8763c90d9fe58909004fe
7.2.1+2e198810a95fdbff698c2180edd4e14a4fabab0f