mirror of
https://github.com/McShelby/hugo-theme-relearn.git
synced 2025-02-15 08:13:32 +00:00
docs: use exampleSite structure in examples #1003
This commit is contained in:
Sören Weber
parent
603c90f266
commit
2a6d621e79
8 changed files with 119 additions and 59 deletions
|
|
@ -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
|
||||
````
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
````
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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,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,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
|
||||
|
|
|
|||
|
|
@ -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/).
|
||||
|
|
|
|||
|
|
@ -1 +1 @@
|
|||
7.3.2+e18b21ac7f2ad06dec4ee7febd63cd1af7971584
|
||||
7.3.2+603c90f266c54338ff40368daffaa2241805e3b6
|
||||
Loading…
Add table
Reference in a new issue