archetypes: rethink rendering #300

This commit is contained in:
Sören Weber 2022-07-05 00:19:27 +02:00
parent d071d2d2a3
commit 897e004e1a
No known key found for this signature in database
GPG key ID: 07D17FF580AE7589
103 changed files with 336 additions and 212 deletions

View file

@ -1,12 +1,8 @@
+++
chapter = true
menuPre = "<b>X. </b>"
archetype = "chapter"
narrow = true
title = "{{ replace .Name "-" " " | title }}"
weight = 5
weight = X
+++
### Chapter X
# Some Chapter title
Lorem Ipsum.

View file

@ -1,6 +1,6 @@
+++
title = "{{ replace .Name "-" " " | title }}"
weight = 5
weight = X
+++
Lorem Ipsum.

6
archetypes/home.md Normal file
View file

@ -0,0 +1,6 @@
+++
archetype = "home"
title = "{{ replace .Name "-" " " | title }}"
++
Lorem Ipsum.

View file

@ -1,9 +1,8 @@
+++
archetype = "home"
title = "Hugo Relearn Theme"
+++
# Hugo Relearn Theme
The [Relearn theme](http://github.com/McShelby/hugo-theme-relearn) is a theme for [Hugo](https://gohugo.io/), a static website generator written in Go. Where Hugo is often used for blogs, this theme is designed with documentation in mind.
{{% notice info %}}

View file

@ -1,4 +1,5 @@
+++
archetype = "home"
title = "Cap'n Hugo Relearrrn Theme"
+++
{{< piratify >}}

View file

@ -1,11 +1,8 @@
+++
chapter = true
archetype = "chapter"
narrow = true
title = "Basics"
weight = 1
+++
### Chapter 1
# Basics
Discover what this Hugo theme is all about and the core-concepts behind it.

View file

@ -1,5 +1,6 @@
+++
chapter = true
archetype = "chapter"
narrow = true
title = "Basics"
weight = 1
+++

View file

@ -14,9 +14,16 @@ This document shows you what's new in the latest release. For a detailed list of
---
## 4.3.0
## 5.0.0
- **Change**: Renaming the frontmatter options `pre` / `post` to `menuPre` / `menuPost`. The old options will still be used if the new options aren't set. Therefore you don't need to change anything after the upgrade.
- **Change**: The way [archetypes]({{% relref "cont/archetypes" %}}) are used to generate output has changed. Your existing content files will still work like before and therefore you don't need to change anything after the upgrade.
Nevertheless, it is recommended to adapt your existing files to the new way.
- for your home page, add the frontmatter parameter `archetype = "home"`
- for all files having the old frontmatter parameter `chapter = true`, replace that parameter with `archetype = "chapter"`
- **Change**: The frontmatter options `pre` / `post` were renamed to `menuPre` / `menuPost`. The old options will still be used if the new options aren't set. Therefore you don't need to change anything after the upgrade.
- **New**: Adding new partials `heading-pre.html` / `heading-post.html` and according frontmatter options `headingPre` / `headingPost` to modifiy the way your page`s main heading gets styled.

View file

@ -1,11 +1,8 @@
+++
chapter = true
archetype = "chapter"
narrow = true
title = "Content"
weight = 2
+++
### Chapter 2
# Content
Find out how to create and organize your content quickly and intuitively.

View file

@ -1,5 +1,6 @@
+++
chapter = true
archetype = "chapter"
narrow = true
title = "Rambl'n"
weight = 2
+++

View file

@ -1,58 +0,0 @@
+++
title = "Archetypes"
weight = 10
+++
Using the command: `hugo new [relative new content path]`, you can start a content file with the date and title automatically set. While this is a welcome feature, active writers need more: [archetypes](https://gohugo.io/content/archetypes/).
It is pre-configured skeleton pages with default front matter. Please refer to the documentation for types of page to understand the differences.
## Chapter {#archetypes-chapter}
To create a Chapter page, run the following commands
```shell
hugo new --kind chapter <name>/_index.md
```
It will create a page with predefined Front-Matter:
```toml
+++
chapter = true
menuPre = "<b>X. </b>"
title = "{{ replace .Name "-" " " | title }}"
weight = 5
+++
### Chapter X
# Some Chapter title
Lorem Ipsum.
```
## Default
To create a default page, run either one of the following commands either
```shell
hugo new <chapter>/<name>/_index.md
```
or
```shell
hugo new <chapter>/<name>.md
```
It will create a page with predefined Front-Matter:
```toml
+++
title = "{{ replace .Name "-" " " | title }}"
weight = 5
+++
Lorem Ipsum.
```

View file

@ -0,0 +1,119 @@
+++
title = "Archetypes"
weight = 10
+++
Using the command: `hugo new [relative new content path]`, you can start a content file with the date and title automatically set. While this is a welcome feature, active writers need more: [archetypes](https://gohugo.io/content/archetypes/). These are preconfigured skeleton pages with default frontmatter.
The Relearn theme defines some few archetypes of pages but you are free to define new ones to your liking. All can be used at any level of the documentation, the only difference being the layout of the content.
## Predefined Archetypes
### Home {#archetypes-home}
A **Home** page is the starting page of your project. It's best to have only one page of this kind in your project.
![Home page](images/pages-home.png?classes=shadow&width=60pc)
To create a home page, run the following command
```shell
hugo new --kind home _index.md
```
This leads to a file with the following content
```markdown
+++
archetype = "home"
title = "{{ replace .Name "-" " " | title }}"
+++
Lorem Ipsum.
```
### Chapter {#archetypes-chapter}
A **Chapter** displays a page meant to be used as introduction for a set of child pages. Commonly, it contains a simple title and a catch line to define content that can be found below it.
![Chapter page](images/pages-chapter.png?classes=shadow&width=60pc)
To create a chapter page, run the following command
```shell
hugo new --kind chapter <name>/_index.md
```
This leads to a file with the following content
```markdown
+++
archetype = "chapter"
narrow = true
title = "{{ replace .Name "-" " " | title }}"
weight = X
+++
Lorem Ipsum.
```
Replace the `X` with a number. Because this number will be used to generate the subtitle of the content page, set the number to a consecutive value starting at 1 for each new chapter level.
### Default {#archetypes-default}
A **Default** page is any other content page. If you set an unknown archetype in your frontmatter, this archetype will be used to generate the page.
![Default page](images/pages-default.png?classes=shadow&width=60pc)
To create a default page, run either one of the following commands
```shell
hugo new <chapter>/<name>/_index.md
```
or
```shell
hugo new <chapter>/<name>.md
```
This leads to a file with the following content
```markdown
+++
title = "{{ replace .Name "-" " " | title }}"
weight = X
+++
Lorem Ipsum.
```
Replace the `X` with a number or delete the whole `weight` parameter entirly.
## Selfdefined Archetypes
If you are in need of further archetypes you can define your own or even redefine existing ones.
### Template
Define a template file in your project at `archetypes/<kind>.md` and make sure it has at least the frontmatter parameter for that archetype like
````markdown
+++
archetype = "<kind>"
+++
````
Afterwards you can generate new content files of that kind with the follwing command
```shell
hugo new --kind <kind> <name>/_index.md
```
### Partial
To define how your archetypes are rendered, define a corresponding file in your project at `layouts/partials/archetypes/<kind>.html`.
Take a look at the existing archetypes of this theme to get an idea how to utilize it.
If you use an unknown archetype in your frontmatter, the `default` archetype will be used to generate the page.

View file

Before

Width:  |  Height:  |  Size: 154 KiB

After

Width:  |  Height:  |  Size: 154 KiB

View file

Before

Width:  |  Height:  |  Size: 239 KiB

After

Width:  |  Height:  |  Size: 239 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 100 KiB

View file

@ -49,7 +49,7 @@ Be aware that only translated pages are displayed in menu. It's not replaced wit
{{% /notice %}}
{{% notice tip %}}
Use [slug](https://gohugo.io/content-management/multilingual/#translate-your-content) Front Matter parameter to translate urls too.
Use [slug](https://gohugo.io/content-management/multilingual/#translate-your-content) frontmatter parameter to translate urls too.
{{% /notice %}}
## Search

View file

@ -39,52 +39,10 @@ content
`_index.md` is required in each folder, its your “folder home page”
{{% /notice %}}
## Types
The Relearn theme defines two types of pages. *Default* and *Chapter*. Both can be used at any level of the documentation, the only difference being layout display.
### Chapter {#chapter-style}
A **Chapter** displays a page meant to be used as introduction for a set of child pages. Commonly, it contains a simple title and a catch line to define content that can be found under it.
You can define any HTML as prefix for the menu. In the example below, it's just a number but that could be an [icon](https://fortawesome.github.io/Font-Awesome/).
![Chapter page](images/pages-chapter.png?classes=shadow&width=60pc)
```markdown
+++
chapter = true
menuPre = "<b>1. </b>"
title = "Basics"
weight = 5
+++
### Chapter 1
# Basics
Discover what this Hugo theme is all about and the core-concepts behind it.
```
To tell the Relearn theme to consider a page as a chapter, set `chapter=true` in the Front Matter of the page.
### Default
A **Default** page is any other content page.
![Default page](images/pages-default.png?classes=shadow&width=60pc)
```toml
+++
title = "Installation"
weight = 15
+++
```
The following steps are here to help you initialize your new website. If you don't know Hugo at all, we strongly suggest you to train by following this [great documentation for beginners](https://gohugo.io/overview/quickstart/).
## Create your project
The following steps are here to help you initialize your new website. If you don't know Hugo at all, we strongly suggest you to train by following [great documentation for beginners](https://gohugo.io/overview/quickstart/).
Hugo provides a `new` command to create a new website.
```shell
@ -93,11 +51,11 @@ hugo new site <new_project>
The Relearn theme provides [archetypes]({{%relref "cont/archetypes" %}}) to help you create this kind of pages.
## Front Matter configuration
## Frontmatter Configuration
Each Hugo page has to define a [Front Matter](https://gohugo.io/content/front-matter/) in *toml*, *yaml* or *json*. This site will use *toml* in all cases.
Each Hugo page has to define a [frontmatter](https://gohugo.io/content/front-matter/) in *toml*, *yaml* or *json*. This site will use *toml* in all cases.
The Relearn theme uses the following parameters on top of Hugo ones :
The Relearn theme uses the following parameters on top of Hugo ones:
```toml
+++
@ -118,8 +76,8 @@ headingPost = ""
menuPre = ""
# The title of the page in menu will be postfixed by this HTML content
menuPost = ""
# Set the page as a chapter, changing the way it's displayed
chapter = false
# Makes the content more narrow, increases font-size and alignment
narrow = false
# Hide a menu entry by setting this to true
hidden = false
# Display name of this page modifier. If set, it will be displayed in the footer.
@ -185,11 +143,3 @@ The theme generates the menu based on the following rules:
- all remaining entries are not shown
You can see this feature in action on the example page for [children shortcode]({{< relref "shortcodes/children" >}}) and its children pages.
## Your Page
To configure your page, you basically have three choices:
1. Create an `_index.md` document in `content` folder and fill the file with *Markdown content*
2. Create an `index.html` file in the `static` folder and fill the file with *HTML content*
3. Configure your server to automatically redirect home page to one your documentation page

View file

@ -1,13 +1,10 @@
+++
chapter = true
archetype = "chapter"
narrow = true
title = "Shortcodes"
weight = 3
+++
### Chapter 3
# Shortcodes
Hugo uses Markdown for its simple content format. However, there are a lot of things that Markdown doesnt support well. You could use pure HTML to expand possibilities.
But this happens to be a bad idea. Everyone uses Markdown because it's pure and simple to read even non-rendered. You should avoid HTML to keep it as simple as possible.

View file

@ -1,5 +1,6 @@
+++
chapter = true
archetype = "chapter"
narrow = true
title = "Shorrrtcodes"
weight = 3
+++

View file

@ -1,14 +1,11 @@
+++
chapter = true
archetype = "chapter"
hidden = true
narrow = true
title = "Tests"
weight = 4
+++
### Chapter 4
# Tests
Some pages for internal testing of differnt styles
{{%children containerstyle="div" style="h2" description="true" %}}

View file

@ -1,7 +1,8 @@
+++
chapter = true
archetype = "chapter"
hidden = true
narrow = true
title = "Tests"
weight = 5
weight = 4
+++
{{< piratify >}}

View file

@ -0,0 +1,6 @@
+++
alwaysopen = false
title = "Chapters"
+++
Start your success story. Now!

View file

@ -0,0 +1,5 @@
+++
alwaysopen = false
title = "Chapters"
+++
{{< piratify >}}

View file

@ -1,12 +0,0 @@
+++
chapter = true
hidden = true
title = "This could be yours"
weight = 4
+++
### Chapter 4
# This could be yours
Start your success story. Now!

View file

@ -1,7 +0,0 @@
+++
chapter = true
hidden = true
title = "This could be yers"
weight = 4
+++
{{< piratify >}}

View file

@ -1 +1 @@
{{ if .Params.chapter }}{{ .Params.weight }}. {{ end }}
{{ if (eq .Params.archetype "chapter") }}{{ .Params.weight }}. {{ end }}

View file

@ -66,3 +66,6 @@ other = "نسخ الرابط إلى الحافظة"
[Link-copied-to-clipboard]
other = "رابط نسخت إلى الحافظة!"
[Chapter]
other = "{{.}} الفصل"

View file

@ -66,3 +66,6 @@ other = "Link in Zwischenablage kopieren"
[Link-copied-to-clipboard]
other = "Link in Zwischenablage kopiert!"
[Chapter]
other = "Kapitel {{.}}"

View file

@ -66,3 +66,6 @@ other = "Copy link to clipboard"
[Link-copied-to-clipboard]
other = "Copied link to clipboard!"
[Chapter]
other = "Chapter {{.}}"

View file

@ -66,3 +66,6 @@ other = "Copiar enlace al portapapeles"
[Link-copied-to-clipboard]
other = "¡Enlace copiado al portapapeles!"
[Chapter]
other = "Capitulo {{.}}"

View file

@ -66,3 +66,6 @@ other = "Copier le lien dans le presse-papiers"
[Link-copied-to-clipboard]
other = "Lien copié dans le presse-papiers!"
[Chapter]
other = "Chapitre {{.}}"

View file

@ -66,3 +66,6 @@ other = "क्लिपबोर्ड पर लिंक की प्रत
[Link-copied-to-clipboard]
other = "लिंक क्लिपबोर्ड के लिए प्रतिलिपि बनाई!"
[Chapter]
other = "अध्याय {{.}}"

View file

@ -66,3 +66,6 @@ other = "Salin link ke clipboard"
[Link-copied-to-clipboard]
other = "Link disalin ke clipboard!"
[Chapter]
other = "Bab {{.}}"

View file

@ -66,3 +66,6 @@ other = "Copia collegamento in clipboard"
[Link-copied-to-clipboard]
other = "Collegamento copiato dalla clipboard!"
[Chapter]
other = "Capitolo {{.}}"

View file

@ -66,3 +66,6 @@ other = "リンクをクリップボードにコピー"
[Link-copied-to-clipboard]
other = "リンクをクリップボードにコピーしました!"
[Chapter]
other = "第{{.}}章"

View file

@ -69,3 +69,6 @@ other = "링크를 클립보드에 복사"
[Link-copied-to-clipboard]
other = "클립보드에 링크가 복사됐습니다!"
[Chapter]
other = "{{.}}장"

View file

@ -66,3 +66,6 @@ other = "Link naar klembord kopiëren"
[Link-copied-to-clipboard]
other = "Link gekopieerd naar klembord!"
[Chapter]
other = "Hoofdstuk {{.}}"

View file

@ -66,3 +66,6 @@ other = "Copy link t' clipboard"
[Link-copied-to-clipboard]
other = "Copied link t' clipboard!"
[Chapter]
other = "T' chapterrr {{.}}"

View file

@ -66,3 +66,6 @@ other = "Kopiuj link do schowka"
[Link-copied-to-clipboard]
other = "Skopiowano link do schowka!"
[Chapter]
other = "Rozdział {{.}}"

View file

@ -66,3 +66,6 @@ other = "Link de cópia para a área de transferência"
[Link-copied-to-clipboard]
other = "Link copiado para a área de transferência!"
[Chapter]
other = "Capítulo {{.}}"

View file

@ -66,3 +66,6 @@ other = "Скопировать ссылку в буфер обмена"
[Link-copied-to-clipboard]
other = "Ссылка скопирована в буфер обмена!"
[Chapter]
other = "Глава {{.}}"

View file

@ -66,3 +66,6 @@ other = "Bağlantıyı panoya kopyala"
[Link-copied-to-clipboard]
other = "Panoya bağlantı kopyalanmış!"
[Chapter]
other = "{{.}}. Bölüm"

View file

@ -69,3 +69,6 @@ other = "Sao chép nối kết vào bảng tạm"
[Link-copied-to-clipboard]
other = "Liên kết được sao chép vào bảng tạm!"
[Chapter]
other = "Chương {{.}}"

View file

@ -66,3 +66,6 @@ other = "将链接复制到剪贴板"
[Link-copied-to-clipboard]
other = "链接复制到剪贴板!"
[Chapter]
other = "第{{.}}章"

View file

@ -66,3 +66,6 @@ other = "將連結複製到剪貼簿"
[Link-copied-to-clipboard]
other = "連結複製到剪貼簿!"
[Chapter]
other = "第{{.}}章"

View file

@ -66,3 +66,6 @@ other = "将链接复制到剪贴板"
[Link-copied-to-clipboard]
other = "链接复制到剪贴板!"
[Chapter]
other = "第{{.}}章"

View file

@ -0,0 +1,10 @@
{{- $content := .content }}
{{- with .page }}
<article class="chapter deprecated">
{{ $content | safeHTML }}
<footer class="footline">
{{- partial "content-footer.html" . }}
</footer>
</article>
{{- end }}

View file

@ -0,0 +1,12 @@
{{- $content := .content }}
{{- with .page }}
<article class="chapter">
{{- partial "heading-pre.html" . }}<div class="article-subheading">{{ T "Chapter" .Params.Weight }}</div>
<h1>{{ .Title }}</h1>{{- partial "heading-post.html" . }}
{{ $content | safeHTML }}
<footer class="footline">
{{- partial "content-footer.html" . }}
</footer>
</article>
{{- end }}

View file

@ -0,0 +1,11 @@
{{- $content := .content }}
{{- with .page }}
<article class="default">
{{- partial "heading-pre.html" . }}<h1>{{ .Title }}</h1>{{- partial "heading-post.html" . }}
{{ $content | safeHTML }}
<footer class="footline">
{{- partial "content-footer.html" . }}
</footer>
</article>
{{- end }}

View file

@ -0,0 +1,10 @@
{{- $content := .content }}
{{- with .page }}
<article class="home deprecated">
{{ $content | safeHTML }}
<footer class="footline">
{{- partial "content-footer.html" . }}
</footer>
</article>
{{- end }}

View file

@ -0,0 +1,11 @@
{{- $content := .content }}
{{- with .page }}
<article class="home">
{{- partial "heading-pre.html" . }}<h1>{{ .Title }}</h1>{{- partial "heading-post.html" . }}
{{ $content | safeHTML }}
<footer class="footline">
{{- partial "content-footer.html" . }}
</footer>
</article>
{{- end }}

View file

@ -1,11 +1,12 @@
{{- $content := .content }}
{{- with .page }}
<article{{if .Params.chapter}} class="chapter"{{end}}>
{{ if and (not .IsHome ) (not .Params.chapter) }}{{- partial "heading-pre.html" . }}<h1>{{ .Title }}</h1>{{- partial "heading-post.html" . }}
{{ end }}{{ $content | safeHTML }}
<footer class="footline">
{{- partial "content-footer.html" . }}
</footer>
</article>
{{- $archetype := "default" }}
{{- if .page.Params.archetype }}
{{- $archetype = .page.Params.archetype }}
{{- else if .page.Params.chapter }}
{{- $archetype = "chapter-deprecated" }}
{{- else if .page.IsHome }}
{{- $archetype = "home-deprecated" }}
{{- end }}
{{- if not (fileExists (printf "/layouts/partials/archetypes/%s.html" $archetype)) }}
{{- $archetype = "default" }}
{{- end }}
{{- partial (printf "archetypes/%s.html" $archetype) (dict "page" .page "content" .content) }}

View file

@ -18,7 +18,7 @@
{{- else }}
{{- if $isActive }}
{{- template "section-print" dict "sect" . "currentnode" $currentNode }}
{{- if or .IsHome .Params.chapter $pages }}
{{- if or $pages }}
<section>
{{- end }}
{{- end }}
@ -32,7 +32,7 @@
{{- end }}
{{- end }}
{{- if $isActive }}
{{- if or .IsHome .Params.chapter $pages }}
{{- if $pages }}
</section>
{{- end }}
{{- end }}
@ -59,7 +59,7 @@
{{- $currentOrdersectionsby := .Params.ordersectionsby | default $defaultOrdersectionsby }}
{{- if $isActive }}
{{- template "section-print" dict "sect" . "currentnode" $currentNode }}
{{- if or .IsHome .Params.chapter $pages }}
{{- if $pages }}
<section>
{{- end }}
{{- end }}
@ -73,7 +73,7 @@
{{- end }}
{{- end }}
{{- if $isActive }}
{{- if or .IsHome .Params.chapter $pages }}
{{- if $pages }}
</section>
{{- end }}
{{- end }}

View file

@ -79,7 +79,7 @@
{{- $defaultDisableToc := .Site.Params.disableToc | default false }}
{{- $currentDisableToc := .Params.disableToc | default $defaultDisableToc }}
{{- $hastoc := not (eq 0 (int (len (.TableOfContents | plainify)))) }}
{{- $toc := (and $hastoc (not $currentDisableToc) (not .Params.chapter)) }}
{{- $toc := (and $hastoc (not $currentDisableToc)) }}
<div id="breadcrumbs">
<span id="sidebar-toggle-span">
<a href="#" id="sidebar-toggle" title='{{ T "Navigation-toggle" }} (CTRL+ALT+m)'><i class="fas fa-bars fa-fw"></i></a>
@ -104,7 +104,7 @@
{{- end }}
</div>
</nav>
<main id="body-inner" class="highlightable{{if .Params.chapter}} chapter{{end}}" tabindex="-1">
<main id="body-inner" class="highlightable{{if (or .Params.narrow .Params.chapter) }} narrow{{end}}" tabindex="-1">
<div class="flex-block-wrapper">
<div id="head-tags">
{{- partial "tags.html" . }}

View file

@ -80,7 +80,8 @@
font-family: "Work Sans", "Helvetica", "Tahoma", "Geneva", "Arial", sans-serif; /* var(--MAIN-font) */
}
h2, h3, h4, h5, h6 {
h2, h3, .article-subheading, h4, h5, h6 {
{
color: #4a4a4a; /* var(--MAIN-TITLES-TEXT-color) */
font-family: "Work Sans", "Helvetica", "Tahoma", "Geneva", "Arial", sans-serif; /* var(--MAIN-TITLES-TEXT-font) */
}

View file

@ -180,7 +180,7 @@ body {
font-size: 1rem;
line-height: 1.5; }
h1, h2, h3, h4, h5, h6 {
h1, h2, h3, .article-subheading, h4, h5, h6 {
margin: 0.85rem 0 1rem 0;
text-rendering: optimizeLegibility; }
@ -190,7 +190,7 @@ h1 {
h2 {
font-size: 2.55rem; }
h3 {
h3, .article-subheading {
font-size: 2.15rem; }
h4 {

View file

@ -54,7 +54,7 @@ pre {
display: none;
}
#body h1, #body h2, #body h3, #body h4, #body h5, #body h6 {
#body h1, #body h2, #body h3, #body .article-subheading, #body h4, #body h5, #body h6 {
/* better contrast for colored elements */
color: black;
}
@ -93,10 +93,12 @@ body,
margin-bottom: 2rem;
padding-bottom: .75rem;
}
#body-inner .chapter h3:first-of-type {
#body-inner div.article-subheading,
#body-inner .chapter.deprecated h3:first-of-type {
margin-top: 2rem;
}
#body-inner .chapter p {
#body-inner.narrow p {
font-size: 1rem;
}

Some files were not shown because too many files have changed in this diff Show more