hugo-theme-relearn/exampleSite/content/cont/frontmatter/_index.en.md

88 lines
3.1 KiB
Markdown
Raw Normal View History

+++
title = "Frontmatter"
weight = 2
+++
2024-03-02 10:04:52 +00:00
Each Hugo page **has to define** a [frontmatter](https://gohugo.io/content/front-matter/).
2024-03-02 10:04:52 +00:00
## All Frontmatter Options
2024-03-02 10:04:52 +00:00
The values reflect example options. The defaults can be taken from the [annotated example](#annotated-frontmatter-options) below.
2024-03-02 10:04:52 +00:00
{{< multiconfig fm=true >}}
{{% include "frontmatter.toml" %}}
2024-03-02 10:04:52 +00:00
{{< /multiconfig >}}
2024-03-02 10:04:52 +00:00
## Annotated Frontmatter Options
2024-03-02 10:04:52 +00:00
````toml {title="toml"}
+++
{{% include "frontmatter.toml" %}}+++
````
## Some Detailed Examples
### Add Icon to a Menu Entry
In the page frontmatter, add a `menuPre` param to insert any HTML code before the menu label. The example below uses the GitHub icon.
2024-03-02 10:04:52 +00:00
{{< multiconfig fm=true >}}
title = "GitHub repo"
menuPre = "<i class='fab fa-github'></i> "
2024-03-02 10:04:52 +00:00
{{< /multiconfig >}}
![Title with icon](frontmatter-icon.png?width=18.75rem)
### Ordering Sibling Menu/Page Entries
Hugo provides a [flexible way](https://gohugo.io/content/ordering/) to handle order for your pages.
The simplest way is to set `weight` parameter to a number.
2024-03-02 10:04:52 +00:00
{{< multiconfig fm=true >}}
title = "My page"
weight = 5
2024-03-02 10:04:52 +00:00
{{< /multiconfig >}}
### Using a Custom Title for Menu Entries
2024-02-17 11:46:23 +00:00
By default, the Relearn theme will use a page's `title` attribute for the menu item.
2024-02-17 11:46:23 +00:00
But a page's title has to be descriptive on its own while the menu is a hierarchy. Hugo adds the `linkTitle` parameter for that purpose:
For example (for a page named `content/install/linux.md`):
2024-03-02 10:04:52 +00:00
{{< multiconfig fm=true >}}
title = "Install on Linux"
2024-02-17 11:46:23 +00:00
linkTitle = "Linux"
2024-03-02 10:04:52 +00:00
{{< /multiconfig >}}
### Override Expand State Rules for Menu Entries
You can change how the theme expands menu entries on the side of the content with the `alwaysopen` setting on a per page basis. If `alwaysopen=false` for any given entry, its children will not be shown in the menu as long as it is not necessary for the sake of navigation.
The theme generates the menu based on the following rules:
- all parent entries of the active page including their siblings are shown regardless of any settings
- immediate children entries of the active page are shown regardless of any settings
- if not overridden, all other first level entries behave like they would have been given `alwaysopen=false`
- if not overridden, all other entries of levels besides the first behave like they would have been given `alwaysopen=true`
- all visible entries show their immediate children entries if `alwaysopen=true`; this proceeds recursively
- all remaining entries are not shown
You can see this feature in action on the example page for [children shortcode](shortcodes/children) and its children pages.
## Disable Section Pages
2024-04-12 15:30:16 +00:00
You may want to structure your pages in a hierarchical way but don't want to generate pages for those sections? The theme got you covered.
To stay with the initial example: Suppose you want `level-one` 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 show an expander.
For this, open `content/level-one/_index.md` and add the following frontmatter
2024-03-02 10:04:52 +00:00
{{< multiconfig fm=true >}}
collapsibleMenu = true
[_build]
2024-03-02 10:04:52 +00:00
render = "never"
{{< /multiconfig >}}