Pages and Menu Setup

Tip

The homepage setup is documented separately; see here.

Note

The author prefers TOML for the site-wide config and YAML for Front Matter. Please pay attention and convert formats as needed with your favorite tool.

Search#

In your site config hugo.toml, under the [outputs] table, add "json" to the home output formats:

[outputs]  # The `outputs` table lives at the top level of TOML
  home = ["html", "rss", "json"]  # Ask Hugo to emit a JSON index

This setting makes Hugo output your site’s index as JSON at the site root, which the search JavaScript consumes. For details on output formats, see Hugo’s official docs.

Next, create search.md under your project’s content/ directory and add the following Front Matter:

---
layout          : "search"  # required
title           : "Search"
description     : "Use the Up/Down keys to select a result, then press Enter to open."
---

<!-- You can also write Markdown here if you want body content on the page -->

Important

The file must live at content/search.md (top level).

Tip

For multilingual sites, create one per language:

content/
├── search.md     # default language
├── search.ja.md  # other locales
└── ...

Archives#

Create archives.md under content/, and add the following Front Matter:

---
layout          : "archives"  # required
title           : "Archives"
description     : "You can find all past content here."
---

<!-- You can also write Markdown here if you want body content on the page -->

Tip

For multilingual sites, create one per language:

content/
├── archives.md     # default language
├── archives.ja.md  # other locales
└── ...

Categories and Tags#

When writing posts, add categories = [...] and tags = [...] in the Front Matter:

---
title           : "Post title"
date            : 2025-08-14T01:01:00+08:00
description     : "SEO description"
summary         : "Post summary"
categories      : ["Some category", "Another category"]
tags            : ["tag-a", "tag-b"]

params:
  neso:
  # other settings...
---

Then see “Set up the main menu” below to add the Category or Tag pages to your menu (optional).

Note

tags and categories are just two default taxonomies that Hugo provides. You can define your own taxonomies for other kinds of classification. See Taxonomy.

Set up the main menu#

Refer to Hugo’s official Menu documentation for details. Below is an example that adds Tags, Categories, Search, and Archives to the main menu.

Add the following to your hugo.toml:

[menus]  # The `menus` table lives at the top level of TOML
  [[menus.main]]
    identifier = "posts"   # unique id
    name       = "Posts"   # text shown in the menu
    pageRef    = "/posts"  # your content section
    weight     = 10        # order (smaller appears earlier)
  [[menus.main]]
    identifier = "tags"
    name       = "Tags"
    pageRef    = "/tags"   # your taxonomy: tags, categories, etc.
    weight     = 20
  [[menus.main]]
    identifier = "categories"
    name       = "Categories"
    pageRef    = "/categories"  # your taxonomy: tags, categories, etc.
    weight     = 30
  [[menus.main]]
    identifier = "archives"
    name       = "Archives"
    pageRef    = "/archives"  # archives page
    weight     = 40
  [[menus.main]]
    identifier = "search"
    name       = "Search"
    pageRef    = "/search"  # search page
    weight     = 50
  [[menus.main]]
    identifier = "github"
    name       = "GitHub"
    url        = "https://github.com/babeneso"  # external link
    weight     = 60

Important

While name alone works, it is strongly recommended to set an identifier.

For internal links, prefer pageRef and point to the page’s logical path instead of using url.

Use url for external links only, not pageRef.

Note

For multilingual menus, see Hugo’s docs here, or use this demo site’s hugo.toml as a reference.

🚧 TODO

I should explain why Tags and Categories pages render correctly even without corresponding Markdown files, and add that here later.