nishiki/hugo-theme-relearn
1
0
Fork 0
mirror of https://github.com/McShelby/hugo-theme-relearn.git synced 2025-02-15 00:03:32 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

docs: use exampleSite structure in examples #1003

Browse source
This commit is contained in:
Sören Weber 2025-02-14 00:07:05 +01:00
parent 603c90f266
commit 2a6d621e79
No known key found for this signature in database
GPG key ID: BEC6D55545451B6D
8 changed files with 119 additions and 59 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

18
docs/content/authoring/frontmatter/designs/_index.en.md
View file

@ -18,14 +18,14 @@ Regardless of shipped or custom page design, you are using them in the same way.
- If you have an [archetype file](https://gohugo.io/content-management/archetypes/), you can just do
````shell
hugo new --kind chapter chapter1/_index.md
hugo new --kind chapter log/_index.md
````
- 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.
````toml {title="_index.md"}
````toml {title="log/_index.md"}
+++
title = "Chapter 1"
title = "Captain's Log"
type = "chapter"
+++
````
@ -55,7 +55,7 @@ Commonly, it contains a title front matter and a short description in the conten
To create a chapter page, run the following command
````shell
hugo new --kind chapter chapter1/_index.md
hugo new --kind chapter log/_index.md
````
If a numerical `weight` front matter is set, it will be used to generate the subtitle of the chapter page. Set the number to a consecutive value starting at 1 for each new chapter on the same directory level.
@ -69,13 +69,19 @@ A **Default** page is any other content page.
To create a default page, run either one of the following commands
````shell
hugo new chapter1/page1/_index.md
hugo new log/first-day/_index.md
````
or
````shell
hugo new chapter1/page1.md
hugo new log/second-day/index.md
````
or
````shell
hugo new log/third-day.md
````
![Default page](pages-default.png?width=60pc)

9
docs/content/authoring/structure/index.en.md
View file

@ -13,18 +13,19 @@ Organize your site like [any other Hugo project](https://gohugo.io/content/struc
````plaintext
content
├── first-chapter
│ ├── first-page
├── log
│ ├── first-day
| | |── _index.md
| │ ├── first-sub-page
| | | |── _index.md
| | | |── picture1.png
| | | └── plain.txt
│ ├── second-page
│ ├── second-day
| | |── index.md
| | |── picture1.png
| | └── picture2.png
│ └── third-page.md
│ ├── third-day.md
│ └── _index.md
└── _index.md
````

2
docs/content/configuration/customization/topbar/_index.en.md
View file

@ -36,7 +36,7 @@ The theme ships with the following predefined buttons (from left to right in the
- {{% button style="transparent" icon="bars" %}}{{% /button %}} [**sidebar**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/sidebar.html): opens the sidebar flyout if in mobile layout
- {{% button style="transparent" icon="list-alt" %}}{{% /button %}} [**toc**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/toc.html): [opens the table of contents in an overlay](authoring/frontmatter/topbar#table-of-contents)
- {{% button style="transparent" icon="pen" %}}{{% /button %}} [**edit**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/edit.html): browses to the editable page if the `editURL` [parameter is set](authoring/frontmatter/topbar#edit-button)
- {{% button style="transparent" icon="code" %}}{{% /button %}} **source**: [**source**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/markdown.html): browses to the chapter's source code if [markdown support](configuration/sitemanagement/outputformats#source-support) was activated
- {{% button style="transparent" icon="code" %}}{{% /button %}} [**source**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/markdown.html): browses to the chapter's source code if [markdown support](configuration/sitemanagement/outputformats#source-support) was activated
- {{% button style="transparent" icon="fa-fw fab fa-markdown" %}}{{% /button %}} [**markdown**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/markdown.html): browses to the chapter's markdown source if [markdown support](configuration/sitemanagement/outputformats#markdown-support) was activated
- {{% button style="transparent" icon="print" %}}{{% /button %}} [**print**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/print.html): browses to the chapter's printable page if [print support](configuration/sitemanagement/outputformats#print-support) was activated
- {{% button style="transparent" icon="chevron-left" %}}{{% /button %}} [**prev**](https://github.com/McShelby/hugo-theme-relearn/blob/main/layouts/partials/topbar/button/prev.html): browses to the [previous page](authoring/frontmatter/topbar#arrow-navigation) if there is one

63
docs/content/configuration/sidebar/menus/_index.en.md
View file

@ -115,9 +115,9 @@ You may want to structure your entries in a hierarchical way but don't want to g
### For Page Menus
To stay with the [initial example](authoring/structure): Suppose you want `first-chapter/first-page` appear in the sidebar but don't want to generate a page for it. So the entry in the sidebar should not be clickable but should be expandable.
To stay with the [initial example](authoring/structure): Suppose you want `log/first-day` appear in the sidebar but don't want to generate a page for it. So the entry in the sidebar should not be clickable but should be expandable.
For this, open `content/first-chapter/first-page/_index.md` and add the following front matter
For this, open `content/log/first-day/_index.md` and add the following front matter
{{< multiconfig fm=true >}}
[_build]
@ -224,9 +224,9 @@ sidebarmenus = [
## Redefining Sidebar Menus for Certain Pages
Suppose you are building a site that contains a topmost `blog` and `documentation` section.
Suppose you are building a site that contains a topmost `log` and `ship` section.
When the user is on one of the blog pages he should only see a page menu containing all blog pages, while on a documentation page he should only see a page menu containing all doc pages.
When the user is on one of the log pages he should only see a page menu containing all log pages, while on one of the ship pages she should only see a page menu containing all sub pages of the ship section.
For both sections, the default `shortcuts` Hugo menu should be displayed as if [defaults menus](#defining-sidebar-menus) were used.
@ -234,76 +234,75 @@ Directory structure:
````plaintext
content
├── blog
│ ├── post-1.md
│ ├── post-2.md
│ ├── post-3.md
├── log
│ ├── first-day.md
│ ├── second-day.md
│ ├── third-day.md
│ └── _index.md
├── docs
│ ├── topic-1.md
│ ├── topic-2.md
│ ├── topic-3.md
├── ship
│ ├── cargo.md
│ ├── midst.md
│ ├── upper.md
│ └── _index.md
└── _index.md
````
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} Using [Hugo's cascade feature](https://gohugo.io/content-management/front-matter/#cascade), we can redefine the menus once in `blog/_index.md` and `docs/_index.md` setting `sidebarmenus` so they will be used in all children pages.
{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} Using [Hugo's cascade feature](https://gohugo.io/content-management/front-matter/#cascade), we can redefine the menus once in `log/_index.md` and `ship/_index.md` setting `sidebarmenus` so they will be used in all children pages.
Setting the `sidebarmenus` Front Matter will overwrite all default menus. If you want to display the `shortcuts` Hugo menu as well like in this example, you have to declare it with the Front Matter as given in the [default options](#defining-sidebar-menus).
{{< multiconfig fm=true file="blog/_index.md">}}
title = 'Blog'
{{< multiconfig fm=true file="log/_index.md">}}
title = "Captain's Log"
[[cascade]]
[cascade.params]
sidebarmenus = [
{ type = 'page', identifier = 'blog', pageRef = '/blog' },
{ type = 'page', identifier = 'log', pageRef = '/log' },
{ type = 'menu', identifier = 'shortcuts' },
]
{{< /multiconfig >}}
{{< multiconfig fm=true file="docs/_index.md">}}
title = 'Documentation'
{{< multiconfig fm=true file="ship/_index.md">}}
title = 'The Ship'
[[cascade]]
[cascade.params]
sidebarmenus = [
{ type = 'page', identifier = 'docs', pageRef = '/docs' },
{ type = 'page', identifier = 'ship', pageRef = '/ship' },
{ type = 'menu', identifier = 'shortcuts' },
]
{{< /multiconfig >}}
## Displaying Arbitrary Links in a Page Menu
You may have the need to add arbitrary links at some point in your menu that are initially not backed by a page. These are called crosslinks.
You may have the need to add arbitrary links at some point in your menu that should redirect to other pages in your site structure. These are called crosslinks.
Assume the following structure
````plaintext
content
├── reference
│ ├── ref-a.md
│ ├── ref-b.md
│ ├── ref-c.md
├── log
│ ├── first-day.md
│ ├── second-day.md
│ ├── third-day.md
│ └── _index.md
├── topic-blue.md
├── topic-red.md
├── topic-yellow.md
├── burning-sail-incident.md
├── kraken-incident.md
└── _index.md
````
You now want to include `ref-b` as separate `topic-green` entry after `topic-blue` in your menu.
You now want to add a top level menu entry that points to `third-day` as separate `crows-nest-incident`.
For that create a new page with the following front matter
{{< multiconfig fm=true file="content/topic-green.md" >}}
title = 'Topic Green'
menuPageRef = '/reference/ref-b'
{{< multiconfig fm=true file="content/crows-nest-incident.md" >}}
title = "The Crow's Nest Incident"
menuPageRef = '/log/third-day'
{{< /multiconfig >}}
{{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} If you want to link to an external page instead, you can use `menuUrl` instead of `menuPageRef`.
Pages defining a crosslink are never part of the arrow navigation and are skipped instead.
So with the above example and alphabetical sorting of the menu entries, pressing {{% button style="transparent" icon="chevron-right" %}}{{% /button %}} on `topic-blue` will skip the newly added `topic-green` and instead will load `topic-red`.
So with the above example and alphabetical sorting of the menu entries, pressing {{% button style="transparent" icon="chevron-left" %}}{{% /button %}} on `kraken-incident` page will skip the newly added `crows-nest-incident` and instead will load `burning-sail-incident`.
Having sub pages below a page that has `menuUrl` or `menuPageRef` set in their front matter is undefined.

65
docs/content/configuration/sitemanagement/multilingual/_index.en.md
View file

@ -65,15 +65,17 @@ Here's how to make your site multilingual using [translations by file name](http
````plaintext
├── content
│ ├── first-chapter
│ │ ├── first-page
│ ├── log
│ │ ├── first-day
| | | ├── _index.en.md
| | | └── _index.pir.md
│ │ ├── second-page
│ │ ├── second-day
| | | ├── index.en.md
| | | └── index.pir.md
│ │ ├── third-page.en.md
│ │ └── third-page.pir.md
│ │ ├── third-day.en.md
│ │ ├── third-day.pir.md
│ │ ├── _index.en.md
│ │ └── _index.pir.md
│ ├── _index.en.md
│ └── _index.pir.md
├── themes
@ -84,7 +86,58 @@ Here's how to make your site multilingual using [translations by file name](http
## Translation by Content Directory
The theme also support [translations by content directory](https://gohugo.io/content-management/multilingual/#translation-by-content-directory) which can be configured in a similar way. This is not used in further examples of this documentation.
The theme also support [translations by content directory](https://gohugo.io/content-management/multilingual/#translation-by-content-directory) which can be configured in a similar way.
1. Set up languages in your `hugo.toml` file:
{{< multiconfig file=hugo >}}
defaultContentLanguage = 'en'
[languages]
[languages.en]
weight = 1
languageName = 'English'
languageCode = 'en'
contentDir = 'content/en'
title = 'My Website'
[languages.pir]
weight = 2
languageName = 'Pirrratish'
languageCode = 'art-x-pir'
languageDirection = 'rtl'
contentDir = 'content/pir'
title = 'Arrr, my Website'
{{< /multiconfig >}}
2. Duplicate your content files into separate directories named by their language code:
````plaintext
├── content
│ ├── en
| │ ├── log
| │ │ ├── first-day
| | | | └── _index.md
| │ │ ├── second-day
| | | | └── index.md
| │ │ ├── third-day.md
| │ │ └── _index.md
| │ └── _index.md
│ ├── pir
| │ ├── log
| │ │ ├── first-day
| | | | └── _index.md
| │ │ ├── second-day
| | | | └── index.md
| │ │ ├── third-day.md
| │ │ └── _index.md
| │ └── _index.md
| ├── themes
| │ └── hugo-theme-relearn
| │ └── ...
| └── hugo.toml
````
## Search Settings

9
docs/content/configuration/sitemanagement/structure/_index.en.md
View file

@ -9,12 +9,13 @@ If you've followed the [Getting Started](introduction/quickstart) guide, your di
````plaintext
├── content
│ ├── first-chapter
│ │ ├── first-page
│ ├── log
│ │ ├── first-day
| | | └── _index.md
│ │ ├── second-page
│ │ ├── second-day
| | | └── index.md
│ │ └── third-page.md
│ │ ├── third-day.md
│ │ └── _index.md
│ └── _index.md
├── themes
│ └── hugo-theme-relearn

10
docs/content/introduction/quickstart/_index.en.md
View file

@ -96,19 +96,19 @@ Chapters are top-level pages that contain other pages. They have a special layou
Make your first chapter page
````shell
hugo new --kind chapter first-chapter/_index.md
hugo new --kind chapter log/_index.md
````
The new file `content/first-chapter/_index.md` has a `weight` number in the front matter. This sets the chapter's subtitle and its order in the menu.
The new file `content/log/_index.md` has a `weight` number in the front matter. By the themes default settings this sets the chapter's subtitle and its order in the menu.
### Your First Content Pages
Now make content pages inside the chapter. Here are three ways to do this
````shell
hugo new first-chapter/first-page/_index.md
hugo new first-chapter/second-page/index.md
hugo new first-chapter/third-page.md
hugo new log/first-day/_index.md
hugo new log/second-day/index.md
hugo new log/third-day.md
````
Hugo treats these files differently based on their file names. Learn more in [Hugo's guide](https://gohugo.io/content-management/).

2
layouts/partials/version.txt
View file

@ -1 +1 @@
7.3.2+e18b21ac7f2ad06dec4ee7febd63cd1af7971584
7.3.2+603c90f266c54338ff40368daffaa2241805e3b6