Menu entry 方法 on Hugo 中文文档

Children

Fri, 02 Oct 2026 00:00:00 +0800

渲染嵌套菜单时请使用 Children 方法。

项目配置如下：

[[menus.main]]
name = 'Products'
pageRef = '/product'
weight = 10

[[menus.main]]
name = 'Product 1'
pageRef = '/products/product-1'
parent = 'Products'
weight = 1

[[menus.main]]
name = 'Product 2'
pageRef = '/products/product-2'
parent = 'Products'
weight = 2

模板如下：

<ul>
  {{ range .Site.Menus.main }}
    <li>
      <a href="{{ .URL }}">{{ .Name }}</a>
      {{ if .HasChildren }}
        <ul>
          {{ range .Children }}
            <li><a href="{{ .URL }}">{{ .Name }}</a></li>
          {{ end }}
        </ul>
      {{ end }}
    </li>
  {{ end }}
</ul>

Hugo 渲染出如下 HTML：

HasChildren

Fri, 02 Oct 2026 00:00:00 +0800

渲染嵌套菜单时请使用 HasChildren 方法。

项目配置如下：

[[menus.main]]
name = 'Products'
pageRef = '/product'
weight = 10

[[menus.main]]
name = 'Product 1'
pageRef = '/products/product-1'
parent = 'Products'
weight = 1

[[menus.main]]
name = 'Product 2'
pageRef = '/products/product-2'
parent = 'Products'
weight = 2

模板如下：

<ul>
  {{ range .Site.Menus.main }}
    <li>
      <a href="{{ .URL }}">{{ .Name }}</a>
      {{ if .HasChildren }}
        <ul>
          {{ range .Children }}
            <li><a href="{{ .URL }}">{{ .Name }}</a></li>
          {{ end }}
        </ul>
      {{ end }}
    </li>
  {{ end }}
</ul>

Hugo 渲染出如下 HTML：

Identifier

Fri, 02 Oct 2026 00:00:00 +0800

Identifier 方法返回菜单条目的 identifier 属性。如果自动定义菜单条目，它返回该页面所属的 section（内容区块）。

[[menus.main]]
identifier = 'about'
name = 'About'
pageRef = '/about'
weight = 10

[[menus.main]]
identifier = 'contact'
name = 'Contact'
pageRef = '/contact'
weight = 20

下面的示例在多语言项目中查询翻译表时使用了 Identifier 方法，若翻译表中不存在匹配的键，则回退到 name 属性：

<ul>
  {{ range .Site.Menus.main }}
    <li><a href="{{ .URL }}">{{ or (T .Identifier) .Name }}</a></li>
  {{ end }}
</ul>

KeyName

Fri, 02 Oct 2026 00:00:00 +0800

在下面的菜单定义中，第二个条目没有 identifier，因此 Identifier 方法改为返回其 name 属性：

[[menus.main]]
identifier = 'about'
name = 'About'
pageRef = '/about'
weight = 10

[[menus.main]]
name = 'Contact'
pageRef = '/contact'
weight = 20

下面的示例在多语言项目中查询翻译表时使用了 KeyName 方法，若翻译表中不存在匹配的键，则回退到 name 属性：

Name

Fri, 02 Oct 2026 00:00:00 +0800

如果自动定义菜单条目，Name 方法返回该页面的 LinkTitle，若不存在则回退到其 Title。

如果在前置元数据或项目配置中定义菜单条目，Name 方法返回给定菜单条目的 name 属性。如果未定义 name，且该菜单条目解析到某个页面，则 Name 返回该页面的 LinkTitle，若不存在则回退到其 Title。

<ul>
  {{ range .Site.Menus.main }}
    <li><a href="{{ .URL }}">{{ .Name }}</a></li>
  {{ end }}
</ul>

Page

Fri, 02 Oct 2026 00:00:00 +0800

无论你如何定义菜单条目，与页面关联的条目都可以访问该页面的方法。

在下面的菜单定义中，前两个条目与页面关联，最后一个没有：

[[menus.main]]
pageRef = '/about'
weight = 10

[[menus.main]]
pageRef = '/contact'
weight = 20

[[menus.main]]
name = 'Hugo'
url = 'https://gohugo.io'
weight = 30

在下面的示例中，如果菜单条目与页面关联，渲染锚点元素时使用页面的 RelPermalink 和 LinkTitle。

如果条目未与页面关联，则使用它的 url 和 name 属性。

<ul>
  {{ range .Site.Menus.main }}
    {{ with .Page }}
      <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
    {{ else }}
      <li><a href="{{ .URL }}">{{ .Name }}</a></li>
    {{ end }}
  {{ end }}
</ul>

更多信息请参见菜单模板一节。

PageRef

Fri, 02 Oct 2026 00:00:00 +0800

说明

如果在项目配置中定义菜单条目时指定了 pageRef 属性，Hugo 在渲染该条目时会查找匹配的页面。

如果找到匹配的页面：

URL 方法返回该页面的相对永久链接
Page 方法返回对应的 Page 对象
Page 对象上的 HasMenuCurrent 和 IsMenuCurrent 方法返回预期值

如果没有找到匹配的页面：

Params

Fri, 02 Oct 2026 00:00:00 +0800

在项目配置或前置元数据中定义菜单条目时，可以加入 params 键，为条目附加额外信息。例如：

[[menus.main]]
name = 'About'
pageRef = '/about'
weight = 10

[[menus.main]]
name = 'Contact'
pageRef = '/contact'
weight = 20

[[menus.main]]
name = 'Hugo'
url = 'https://gohugo.io'
weight = 30
[menus.main.params]
  rel = 'external'

使用下面的模板：

<ul>
  {{ range .Site.Menus.main }}
    <li>
      <a href="{{ .URL }}" {{ with .Params.rel }}rel="{{ . }}"{{ end }}>
        {{ .Name }}
      </a>
    </li>
  {{ end }}
</ul>

Hugo 渲染出：

<ul>
  <li><a href="/about/">About</a></li>
  <li><a href="/contact/">Contact</a></li>
  <li><a href="https://gohugo.io" rel="external">Hugo</a></li>
</ul>

更多信息请参见菜单模板一节。

Parent

Fri, 02 Oct 2026 00:00:00 +0800

菜单定义如下：

[[menus.main]]
name = 'Products'
pageRef = '/product'
weight = 10

[[menus.main]]
name = 'Product 1'
pageRef = '/products/product-1'
parent = 'Products'
weight = 1

[[menus.main]]
name = 'Product 2'
pageRef = '/products/product-2'
parent = 'Products'
weight = 2

下面的模板渲染嵌套菜单，在每个子条目旁列出其 parent 属性：

<ul>
  {{ range .Site.Menus.main }}
    <li>
      <a href="{{ .URL }}">{{ .Name }}</a>
      {{ if .HasChildren }}
        <ul>
          {{ range .Children }}
            <li><a href="{{ .URL }}">{{ .Name }}</a> ({{ .Parent }})</li>
          {{ end }}
        </ul>
      {{ end }}
    </li>
  {{ end }}
</ul>

Post

Fri, 02 Oct 2026 00:00:00 +0800

在下面的项目配置中，我们启用了 emoji 短代码的渲染，并在每个菜单条目的前面（pre）和后面（post）各添加一个 emoji 短代码：

enableEmoji = true

[[menus.main]]
name = 'About'
pageRef = '/about'
post = ':point_left:'
pre = ':point_right:'
weight = 10

[[menus.main]]
name = 'Contact'
pageRef = '/contact'
post = ':arrow_left:'
pre = ':arrow_right:'
weight = 20

要渲染该菜单：

Pre

Fri, 02 Oct 2026 00:00:00 +0800

在下面的项目配置中，我们启用了 emoji 短代码的渲染，并在每个菜单条目的前面（pre）和后面（post）各添加一个 emoji 短代码：

enableEmoji = true

[[menus.main]]
name = 'About'
pageRef = '/about'
post = ':point_left:'
pre = ':point_right:'
weight = 10

[[menus.main]]
name = 'Contact'
pageRef = '/contact'
post = ':arrow_left:'
pre = ':arrow_right:'
weight = 20

要渲染该菜单：

Title

Fri, 02 Oct 2026 00:00:00 +0800

Title 方法返回给定菜单条目的 title 属性。如果未定义 title，且该菜单条目解析到某个页面，则 Title 返回该页面的 Title。

<ul>
  {{ range .Site.Menus.main }}
    <li><a href="{{ .URL }}" title="{{ .Title }}>{{ .Name }}</a></li>
  {{ end }}
</ul>

URL

Fri, 02 Oct 2026 00:00:00 +0800

对于与页面关联的菜单条目，URL 方法返回该页面的 RelPermalink；否则返回条目的 url 属性。

<ul>
  {{ range .Site.Menus.main }}
    <li><a href="{{ .URL }}">{{ .Name }}</a></li>
  {{ end }}
</ul>

Weight

Fri, 02 Oct 2026 00:00:00 +0800

如果自动定义菜单条目，Weight 方法返回该页面的 Weight。

如果在前置元数据或项目配置中定义菜单条目，Weight 方法返回 weight 属性，若不存在则回退到该页面的 Weight。

在这个刻意构造的示例中，我们按 weight 限制菜单条目的数量：

<ul>
  {{ range .Site.Menus.main }}
    {{ if le .Weight 42 }}
      <li><a href="{{ .URL }}">{{ .Name }}</a></li>
    {{ end }}
  {{ end }}
</ul>