Version main of the documentation is no longer actively maintained. The site that you are currently viewing is an archived snapshot. For up-to-date documentation, see the latest version.

导航和菜单

为您的 Docsy 站点自定义站点导航。

Docsy为您的网站提供了多种内置导航功能，包括网站菜单、分区菜单和页面菜单。本页向您展示它们的工作原理，以及如何配置和自定义它们以满足您的需求。

顶层菜单

顶层菜单（出现在整个站点的顶部导航栏中）使用您站点的主菜单（main menu）。所有的 Hugo 站点都有一个主菜单（main menu）项数组，可以通过 .Site.Menus 站点变量进行访问，通过页面前置元数据或您站点的 hugo.toml/hugo.yaml/hugo.json 进行填充。

要将页面或章节添加到此菜单中，请将其添加到站点的主菜单（main menu）中，无论是在 hugo.toml/hugo.yaml/hugo.json 中还是在目标页面的前置元数据中（在 _index.md 或_index.html 中作为章节着陆页面）。例如，这里是我们如何将 Documentation 章节着陆页添加到该站点的主菜单中的示例：

+++
title = "Welcome to Docsy"
linkTitle = "Documentation"

[menu.main]
weight = 20
pre = "<i class='fa-solid fa-book'></i>"
+++

---
title: "Welcome to Docsy"
linkTitle: "Documentation"
menu:
  main:
    weight: 20
    pre: <i class='fa-solid fa-book'></i>
---

{
  "title": "Welcome to Docsy",
  "linkTitle": "Documentation",
  "menu": {
    "main": {
      "weight": 20,
      "pre": "<i class='fa-solid fa-book'></i>"
    }
  }
}

该菜单按页面weight从左到右排序。例如，页面weight: 30 的章节索引或页面将出现在菜单中的 Documentation 章节之后，而weight: 10的页面将出现在它之前。

如果要将外部站点的链接添加到此菜单中，请在 hugo.toml/hugo.yaml/hugo.json 中添加，指定weight。

[[menu.main]]
    name = "GitHub"
    weight = 50
    url = "https://github.com/google/docsy/"

menu:
  main:
    - name: GitHub
      weight: 50
      url: 'https://github.com/google/docsy/'

{
  "menu": {
    "main": [
      {
        "name": "GitHub",
        "weight": 50,
        "url": "https://github.com/google/docsy/"
      }
    ]
  }
}

将图标添加到顶层菜单

如 Hugo 文档中所述，您可以使用站点的 hugo.toml/hugo.yaml/hugo.json 或页面前置元数据中定义的主菜单项的 pre 和/或 post 参数为顶层菜单项添加图标。例如，以下配置将 GitHub 图标添加到 GitHub 菜单项，并添加 New! 警报以指示这是菜单的新添加。

[[menu.main]]
    name = "GitHub"
    weight = 50
    url = "https://github.com/google/docsy/"
    pre = "<i class='fa-brands fa-github'></i>"
    post = "<span class='alert'>New!</span>"

menu:
  main:
    - name: GitHub
      weight: 50
      url: 'https://github.com/google/docsy/'
      pre: <i class='fa-brands fa-github'></i>
      post: <span class='alert'>New!</span>

{
  "menu": {
    "main": [
      {
        "name": "GitHub",
        "weight": 50,
        "url": "https://github.com/google/docsy/",
        "pre": "<i class='fa-brands fa-github'></i>",
        "post": "<span class='alert'>New!</span>"
      }
    ]
  }
}

您可以在FontAwesome文档中找到完整的图标列表。Docsy主题默认包含免费的FontAwesome图标。

添加版本下拉菜单

如果在hugo.toml中添加了一些[params.versions]，Docsy主题将在顶级菜单中添加一个版本选择器下拉菜单。

您可以在versioning your docs中了解更多信息。

添加语言下拉菜单

如果在hugo.toml中配置了多种语言，Docsy主题将在顶级菜单中添加一个语言选择器下拉菜单。选择语言将带用户到当前页面的翻译版本，或给定语言的主页。

您可以在 Multi-language support中了解更多信息。

章节菜单

章节菜单位于docs章节的左侧，自动从content树中构建。与顶级菜单一样，按页面或章节索引weight（或按页面创建date，如果未设置weight）排序，页面或索引的title或linkTitle（如果不同）作为菜单中的链接标题。如果一个章节子文件夹除了_index.md或_index.html之外还有其他页面，那么这些页面将作为子菜单出现，再次按weight排序。例如，这是这个页面的元数据，显示它的weight和title：

+++
title = "Navigation and Search"
linkTitle = "Navigation and Search"
date = 2017-01-05T00:00:00.000Z
weight = 3
description = '''
Customize site navigation and search for your Docsy site.
'''
+++

---
title: "Navigation and Search"
linkTitle: "Navigation and Search"
date: 2017-01-05
weight: 3
description: >
  Customize site navigation and search for your Docsy site.  
---

{
  "title": "Navigation and Search",
  "linkTitle": "Navigation and Search",
  "date": "2017-01-05T00:00:00.000Z",
  "weight": 3,
  "description": "Customize site navigation and search for your Docsy site.\n"
}

要从左侧导航菜单中隐藏页面或章节，请在前置元数据中设置toc_hide: true。

要从 docs section landing page的章节摘要中隐藏一个页面，请在该页面的前置元数据中设置hide_summary: true。如果您想从目录菜单和章节摘要列表中隐藏一个页面，您需要在该页面的前置元数据中将toc_hide和hide_summary都设置为true。

+++
title = "My Hidden Page"
weight = 99
toc_hide = true
hide_summary = true
description = '''
Page hidden from both the TOC menu and the section summary list.
'''
+++

---
title: "My Hidden Page"
weight: 99
toc_hide: true
hide_summary: true
description: >
  Page hidden from both the TOC menu and the section summary list.  
---

{
  "title": "My Hidden Page",
  "weight": 99,
  "toc_hide": true,
  "hide_summary": true,
  "description": "Page hidden from both the TOC menu and the section summary list.\n"
}

章节菜单选项

默认情况下，章节菜单完全展开显示当前章节。对于大型站点，这可能会使左侧导航过长，难以扫描。尝试在hugo.toml中设置站点参数ui.sidebar_menu_compact = true。

使用紧凑菜单（.ui.sidebar_menu_compact = true），只显示当前页面的祖先、同级和直接后代。您可以使用可选参数.ui.ul_show来设置所需的菜单深度始终可见。例如，使用.ui.ul_show = 1将始终显示第一级菜单。

除了完全展开和紧凑的菜单选项，您还可以通过在hugo.toml中设置站点参数ui.sidebar_menu_foldable = true来创建折叠菜单。折叠菜单让用户通过在菜单中的父节点旁边切换箭头图标来展开和折叠该菜单章节。

在大型站点上（默认情况下：>2000页），该章节菜单不会为每个页面生成，而是为整个章节进行缓存。然后使用JS设置标记活动菜单项（和菜单路径）的HTML类。您可以使用可选参数.ui.sidebar_cache_limit调整激活缓存的章节菜单的限制。

下面的选项卡窗格列出了您可以在项目配置文件中定义的菜单章节选项。

[params.ui]
sidebar_menu_compact = true
ul_show = 1
sidebar_menu_foldable = true
sidebar_cache_limit = 1000

params:
  ui:
    sidebar_menu_compact: true
    ul_show: 1
    sidebar_menu_foldable: true
    sidebar_cache_limit: 1000

{
  "params": {
    "ui": {
      "sidebar_menu_compact": true,
      "ul_show": 1,
      "sidebar_menu_foldable": true,
      "sidebar_cache_limit": 1000,
    }
  }
}

向章节菜单添加图标

您可以通过在页面前置元数据中设置icon参数（例如icon: fa-solid fa-screwdriver-wrench）向侧边栏中的章节菜单添加图标。

您可以在FontAwesome文档中找到要使用的所有图标的完整列表。Docsy默认包含免费的FontAwesome图标。

开箱即用，如果您想使用图标，您应该为同一菜单级别上的所有项定义图标，以确保适当的外观。如果该图标以不同的方式使用，则可能需要进行个别CSS调整。

向章节菜单添加手动链接

默认情况下，章节菜单完全是从您的章节页面生成的。如果您想在此菜单中添加手动链接，例如链接到外部站点或你站点中的不同章节中的页面，则可以通过在doc层次结构中创建具有适当权重和一些特殊参数的占位符页面文件（frontmatter）来实现这一点，以指定链接详细信息。

要创建占位符页面，请按通常方式在要在该菜单中显示链接的目录中创建一个页面文件，并将manualLink参数添加到其元数据中。如果一个页面在其元数据中具有manualLink，则Docsy会为此页面在章节菜单和章节索引中（章节在着陆页面上的子页面列表中 —— 请参见description in the Docsy docs)生成链接，但该链接目标会被替换为manualLink的值。该链接文本是您的占位符页面的title（如果设置了linkTitle，则是linkTitle）。您还可以使用manualLinkTitle参数设置链接的title属性以及使用manualLinkTarget设置链接目标 —— 例如，如果您希望一个外部链接在新选项卡中打开，则可以将其链接目标设置为_blank。Docsy会自动将rel=noopener添加到打开新标签页的链接中，作为安全最佳实践。

您还可以使用manualLink将其他现有站点页面的附加交叉引用添加到站点中。对于内部链接，您可以选择使用manualLinkRelref参数而不是manualLink来使用内置的Hugo函数relref。如果relref无法在您的站点中找到唯一页面，则Hugo会抛出错误消息。

Note

尽管基于您的占位符文件生成的所有菜单和着陆页链接都根据参数 manualLink 或 manualLinkRelref 设置，但 Hugo 仍会为该文件生成一个常规的 HTML 站点页面，尽管没有生成的链接指向该页面。为避免用户意外着陆到生成的占位符页面时产生混淆，我们建议在该页面的正常内容和/或页面描述中指定外部链接的 URL。

面包屑导航

默认情况下，面包屑导航链接出现在每个页面的顶部。要禁用面包屑导航，请在hugo.toml中设置站点参数ui.breadcrumb_disable = true。

分类结果页面上的每个项（例如，单击一个分类标签，例如：标签/类别）也会显示面包屑导航链接。可以通过在hugo.toml中设置站点参数ui.taxonomy_breadcrumb_disable = true来禁用这些面包屑。

下面的选项卡窗格列出了您可以在项目配置文件中定义的面包屑导航选项。

[params.ui]
breadcrumb_disable = true
taxonomy_breadcrumb_disable = true

params:
  ui:
    breadcrumb_disable: true
    taxonomy_breadcrumb_disable: true

{
  "params": {
    "ui": {
      "breadcrumb_disable": true,
      "taxonomy_breadcrumb_disable": true
    }
  }
}

标题自链接

Docsy 支持使用 Hugo 的’render-heading.html’ [钩子]。

要在您的项目，将“layouts/_default/_markup/render-heading.html”定义为：

{{ template "_default/_markup/td-render-heading.html" . }}

标题自链接锚点类为“.td-heading-self-link”，您可以为您的项目定制。默认情况下，标题自链接样式具有以下默认值：

自链接符号为“#”。
该符号在移动和触摸设备上始终可见，否则仅显示悬停或焦点时可见。

您的项目还可以重用（在您自己的自定义标题渲染钩子中）或覆盖标题自链接模板

‘_default/_markup/_td-heading-self-link.html’，定义于[layouts/_default/_markup/td-render-heading.html]。

[layouts/_default/_markup/td-render-heading.html]：https://github.com/google/docsy/tree/main/layouts/_default/_markup/td-render-heading.html [钩子]：https://gohugo.io/templates/render-hooks/

反馈

当前页面对你有帮助吗？

Glad to hear it!

Sorry to hear that. Please tell us how we can improve.

最后修改 July 6, 2024: Update navigation.md (c1d5d89)