nishiki/hugo-theme-relearn
1
0
Fork 0
mirror of https://github.com/McShelby/hugo-theme-relearn.git synced 2025-06-02 06:54:04 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions2

docs: use exampleSite structure in examples

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
docs/content/configuration
customization/topbar
_index.en.md
sidebar/menus
_index.en.md
sitemanagement
multilingual
_index.en.md
structure
_index.en.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