Main Sections

The mainSections parameter is used to filter pages, default to ["posts", "docs"].

1mainSections = ["blog", "posts", "docs", "notes"]

Front Matter

Front Matter is the place where we put page metadata and parameters, such as title, date and so on.

Formats

Hugo supports three formats of front matter: YAML, TOML and JSON.

  • TOML: identified by opening and closing +++.
  • YAML: identified by opening and closing ---.
  • JSON: a single JSON object surrounded by { and }, followed by a new line.

Let’s take TOML as an example:

1+++
2title = 'Hello world!'
3+++

See also Page Parameters and Hugo Front Matter.

Content Types

You may want to use docs layout in other sections instead of /docs, such as /notes. It’s easy to do that by setting type = "docs" on the front matter.

Archetypes

We can also create a archetype for notes, let’s Hugo take care of the type.

1$ cp themes/hugo-theme-bootstrap/archetypes/default.md archetypes/notes.md

And the append type = "docs" on the front matter of archetypes/notes.md. Now, hugo new notes/blah-blah-blah will copy the content of archetypes/notes.md to your new notes.

Similarly, you can also custom the archetypes for posts, docs and so on.

Write New Articles

Suppose the default language is en.

1$ hugo new posts/new-post/index.md

The command above create a new post written in English. Similarly, we can create a post written in Simplified Chinese:

1$ hugo new posts/new-post/index.zh-cn.md

Please remind that, the created posts are generally in draft state. You’ll need to specify the -D parameter of the command hugo server for previewing. Similarly, you need to change the draft to false or remove draft parameter if you want to publish the article.

Summaries Selection Order

  1. If the description is not empty, then it’ll be used, to use summaries all the time, you should set the post.excerpt as empty string explicitly.
  2. Manual splitting via <!–more–>.
  3. If summary on front matter isn’t empty, then summary will be selected.
  4. The text of content will be cut off by post.excerptMaxLength and formatted in plain text or HTML when post.plainifyExcerpt = true.
1[post]
2  # excerptMaxLength = 120
3  # copyright = false # Whether to display copyright section on each post.
4  # plainifyExcerpt = false # Format excerpt in HTML if false.
  1. The images on front matter are preferred.
  2. Page images resources that match the *feature* pattern. Such as posts/my-page/feature.png, posts/my-page/featured-sample.jpg.

The featured image doesn’t show up above content by default, you’ll need to turn on this feature by following parameter.

config/_default/params.toml

1[post]
2  featuredImage = true

config/_default/params.yaml

1post:
2  featuredImage: true

config/_default/params.json

1{
2   "post": {
3      "featuredImage": true
4   }
5}

Thumbnail Selection Order

  1. The images on front matter are preferred.
  2. Page images resources that match the filename’s patterns: *feature*, *cover* and *thumbnail*. Such as posts/my-page/feature.png, posts/my-page/thumnail.jpg.

The page images resources will be resized to several smaller versions to suit the users devices for saving the bandwidth.

Pinning Posts

You can pin posts on the home page by setting pinned to true on the front matter.

1+++
2title = "Pinned Post"
3pinned = true
4pinnedWeight = 100
5+++

If there is multiple pinned posts, they are sorted by pinnedWeight in descending order.

1pinnedPost = false # Disable pinned posts globally.
2pinnedPostCount = 2 # The number of pinned posts shown on home page.

Showing posts on carousel.

1+++
2carousel = true
3+++

Authors

HBS supports the authors taxonomy. Firstly, you’ll need to enable it by setting the following configuration.

config.toml

1[taxonomies]
2  author = 'authors'

config.yaml

1taxonomies:
2  author: authors

config.json

1{
2   "taxonomies": {
3      "author": "authors"
4   }
5}

And then define the authors on your posts.

1+++
2authors = [
3  "Foo",
4  "Bar"
5]
6+++

Now, the authors will be present on the post meta and sidebar taxonomies.

Finally, we may need to introduce the author in more detail. Take the Foo as an example, just create a page with the following content and save it as /content/authors/foo/index.md.

1---
2title: Razon Yang
3description: Gopher, PHPer, Full Stack Engineer.
4social:
5  github: razonyang
6  twitter: razonyang
7---
  • title: The author display name.
  • description: The introduction.
  • social: Social links.

The author image should be placed at the same folder with pattern avatar*, such as /content/authors/foo/avatar.png. If there is no avatar, the social.email will be used to generate Gravatar avatar.

Up Next