mirror of
https://github.com/McShelby/hugo-theme-relearn.git
synced 2024-12-25 23:28:44 +00:00
191 lines
7.2 KiB
Markdown
191 lines
7.2 KiB
Markdown
+++
|
||
title = "Pages organization"
|
||
weight = 5
|
||
+++
|
||
|
||
In **Hugo**, pages are the core of your site. Once it is configured, pages are definitely the added value to your documentation site.
|
||
|
||
## Folders
|
||
|
||
Organize your site like [any other Hugo project](https://gohugo.io/content/organization/). Typically, you will have a *content* folder with all your pages.
|
||
|
||
````plaintext
|
||
content
|
||
├── level-one
|
||
│ ├── level-two
|
||
│ │ ├── level-three
|
||
│ │ │ ├── level-four
|
||
│ │ │ │ ├── _index.md <-- /level-one/level-two/level-three/level-four
|
||
│ │ │ │ ├── page-4-a.md <-- /level-one/level-two/level-three/level-four/page-4-a
|
||
│ │ │ │ ├── page-4-b.md <-- /level-one/level-two/level-three/level-four/page-4-b
|
||
│ │ │ │ └── page-4-c.md <-- /level-one/level-two/level-three/level-four/page-4-c
|
||
│ │ │ ├── _index.md <-- /level-one/level-two/level-three
|
||
│ │ │ ├── page-3-a.md <-- /level-one/level-two/level-three/page-3-a
|
||
│ │ │ ├── page-3-b.md <-- /level-one/level-two/level-three/page-3-b
|
||
│ │ │ └── page-3-c.md <-- /level-one/level-two/level-three/page-3-c
|
||
│ │ ├── _index.md <-- /level-one/level-two
|
||
│ │ ├── page-2-a.md <-- /level-one/level-two/page-2-a
|
||
│ │ ├── page-2-b.md <-- /level-one/level-two/page-2-b
|
||
│ │ └── page-2-c.md <-- /level-one/level-two/page-2-c
|
||
│ ├── _index.md <-- /level-one
|
||
│ ├── page-1-a.md <-- /level-one/page-1-a
|
||
│ ├── page-1-b.md <-- /level-one/page-1-b
|
||
│ └── page-1-c.md <-- /level-one/page-1-c
|
||
├── _index.md <-- /
|
||
└── page-top.md <-- /page-top
|
||
````
|
||
|
||
{{% notice note %}}
|
||
`_index.md` is required in each folder, it’s 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/).
|
||
|
||
|
||
|
||
```markdown
|
||
+++
|
||
chapter = true
|
||
pre = "<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.
|
||
|
||
|
||
|
||
```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
|
||
|
||
Hugo provides a `new` command to create a new website.
|
||
|
||
```shell
|
||
hugo new site <new_project>
|
||
```
|
||
|
||
The Relearn theme provides [archetypes]({{%relref "cont/archetypes" %}}) to help you create this kind of pages.
|
||
|
||
## Front Matter 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.
|
||
|
||
The Relearn theme uses the following parameters on top of Hugo ones :
|
||
|
||
```toml
|
||
+++
|
||
# Table of contents (toc) is enabled by default. Set this parameter to true to disable it.
|
||
# Note: Toc is always disabled for chapter pages
|
||
disableToc = false
|
||
# If set, this will be used for the page's menu entry (instead of the `title` attribute)
|
||
menuTitle = ""
|
||
# If set, this will explicitly override common rules for the expand state of a page's menu entry
|
||
alwaysopen = true
|
||
# If set, this will explicitly override common rules for the sorting order of a page's submenu entries
|
||
ordersectionsby = "title"
|
||
# The title of the page in menu will be prefixed by this HTML content
|
||
pre = ""
|
||
# The title of the page in menu will be postfixed by this HTML content
|
||
post = ""
|
||
# Set the page as a chapter, changing the way it's displayed
|
||
chapter = 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.
|
||
LastModifierDisplayName = ""
|
||
# Email of this page modifier. If set with LastModifierDisplayName, it will be displayed in the footer
|
||
LastModifierEmail = ""
|
||
+++
|
||
```
|
||
|
||
### Add icon to a menu entry
|
||
|
||
In the page frontmatter, add a `pre` param to insert any HTML code before the menu label. The example below uses the GitHub icon.
|
||
|
||
```toml
|
||
+++
|
||
title = "GitHub repo"
|
||
pre = "<i class='fab fa-github'></i> "
|
||
+++
|
||
```
|
||
|
||
|
||
|
||
### 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.
|
||
|
||
```toml
|
||
+++
|
||
title = "My page"
|
||
weight = 5
|
||
+++
|
||
```
|
||
|
||
### Using a custom title for menu entries
|
||
|
||
By default, the Relearn theme will use a page's `title` attribute for the menu item (or `linkTitle` if defined).
|
||
|
||
But a page's title has to be descriptive on its own while the menu is a hierarchy.
|
||
We've added the `menuTitle` parameter for that purpose:
|
||
|
||
For example (for a page named `content/install/linux.md`):
|
||
|
||
```toml
|
||
+++
|
||
title = "Install on Linux"
|
||
menuTitle = "Linux"
|
||
+++
|
||
```
|
||
|
||
### 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 recursivley
|
||
- 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
|