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

149 lines
5.4 KiB
Markdown
Raw Normal View History

---
date: 2016-04-09T16:50:16+02:00
title: Pages organization
weight: 5
---
2017-08-20 15:10:29 +00:00
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.
2017-08-20 15:10:29 +00:00
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, its your “folder home page”
{{% /notice %}}
## Types
2017-08-20 15:10:29 +00:00
**Hugo-theme-learn** defines two types of pages. *Default* and *Chapter*. Both can be used at any level of the documentation, the only difference being layout display.
2017-08-20 15:10:29 +00:00
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/).
2017-09-04 17:06:19 +00:00
![Chapter page](/cont/pages/images/pages-chapter.png?width=50pc)
2017-08-20 15:10:29 +00:00
```markdown
+++
title = "Basics"
chapter = true
weight = 5
pre = "<b>1. </b>"
+++
2017-08-20 15:10:29 +00:00
### Chapter 1
2017-08-20 15:10:29 +00:00
# Basics
2017-08-20 15:10:29 +00:00
Discover what this Hugo theme is all about and the core-concepts behind it.
```
2017-08-20 20:29:35 +00:00
To tell **Hugo-theme-learn** to consider a page as a chapter, set `chapter=true` in the Front Matter of the page.
2017-08-20 15:10:29 +00:00
A **Default** page is any other content page.
2017-09-04 17:06:19 +00:00
![Default page](/cont/pages/images/pages-default.png?width=50pc)
2017-08-20 15:10:29 +00:00
```toml
+++
title = "Installation"
weight = 15
+++
```
2017-08-20 15:10:29 +00:00
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/).
2017-08-20 15:10:29 +00:00
## Create your project
2017-08-20 15:10:29 +00:00
Hugo provides a `new` command to create a new website.
2017-08-20 15:10:29 +00:00
```
hugo new site <new_project>
```
2017-08-20 20:29:35 +00:00
**Hugo-theme-learn** provides [archetypes]({{< relref "cont/archetypes.fr.md" >}}) to help you create this kind of pages.
2017-08-20 15:10:29 +00:00
## Front Matter configuration
Each Hugo page has to define a [Front Matter](https://gohugo.io/content/front-matter/) in *yaml*, *toml* or *json*.
2017-08-20 15:10:29 +00:00
**Hugo-theme-learn** uses the following parameters on top of Hugo ones :
```toml
+++
2017-08-20 15:10:29 +00:00
# Table of content (toc) is enabled by default. Set this parameter to true to disable it.
# Note: Toc is always disabled for chapter pages
disableToc = "false"
# 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 = ""
+++
```
2017-08-20 15:10:29 +00:00
### Add icon to a menu entry
2017-08-20 15:10:29 +00:00
In the page frontmatter, add a `pre` param to insert any HTML code before the menu label. The example below uses the Github icon.
2017-08-20 15:10:29 +00:00
```toml
+++
title = "Github repo"
pre = "<i class='fa fa-github'></i> "
+++
```
2017-08-20 15:10:29 +00:00
![Title with icon](/cont/pages/images/frontmatter-icon.png)
2017-08-20 15:10:29 +00:00
### Ordering sibling menu/page entries
2017-08-20 15:10:29 +00:00
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
+++
```
## Homepage
2017-08-20 15:10:29 +00:00
To configure your home page, you basically have three choices:
2017-08-20 15:10:29 +00:00
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