3 - 导航和菜单

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 章节着陆页添加到该站点的主菜单中的示例：

• Front matter:
• toml
• yaml
• json

+++
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。

• Configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

[[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! 警报以指示这是菜单的新添加。

• Configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

[[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：

• Front matter:
• toml
• yaml
• json

+++
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。

• Front matter:
• toml
• yaml
• json

+++
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调整激活缓存的章节菜单的限制。

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

• Configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

[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会抛出错误消息。

面包屑导航

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

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

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

• Configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

[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/

4 - 搜索

Docsy 提供了多种选项，让您的读者搜索您的网站内容，因此您可以选择适合您需求的选项。您可以选择：

• [Google 自定义搜索引擎]（#configure-search-with-a-google-custom-search-engine） （GCSE），默认选项，它使用 Google 对您的公共网站的索引来生成搜索结果页面。
• [Algolia DocSearch]（#algolia-docsearch），它使用 Algolia 的索引和搜索机制。搜索结果显示为弹出窗口。Algolia DocSearch 对公共文档网站免费。
• [使用 Lunr 进行本地搜索]（#local-search-with-lunr），它使用 Javascript 索引和搜索您的站点，而无需连接到外部服务。此选项不要求您的网站是公开的。

如果在项目 configuration file 中启用这些搜索选项中的任何一个，则顶部导航栏右侧会显示一个搜索框。默认情况下，搜索框还会显示在左侧导航窗格中部分菜单的顶部，如果您愿意，或者如果您使用的搜索选项仅适用于顶部搜索框，则可以禁用该搜索框。

禁用侧边栏搜索框

默认情况下，搜索框同时显示在顶部导航栏和侧边栏左侧导航窗格的顶部。如果您不想要侧边栏搜索框，请在 ‘hugo.toml’/‘hugo.yaml’/‘hugo.json’ 中将站点参数 ‘sidebar_search_disable’ 设置为 ’true’：

• Configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

[params.ui]
sidebar_search_disable = true

params:
  ui:
    sidebar_search_disable: true

{
  "params": {
    "ui": {
      "sidebar_search_disable": true
    }
  }
}

使用 Google 自定义搜索引擎配置搜索

默认情况下，Docsy 使用 [Google 自定义搜索引擎]（https://cse.google.com/cse/all） （GCSE） 来搜索您的网站。要启用此功能，您首先需要确保已构建并部署了 [网站的生产版本]（/docs/deployment#build-environments-and-indexing），否则您的网站将不会被抓取和索引。

设置网站搜索

1. 点击[自定义搜索页面]（https://cse.google.com/cse/all）上的新搜索引擎，然后按照说明为已部署的网站创建Google自定义搜索引擎。记下新搜索引擎的 ID。
2. 使用“编辑搜索引擎”选项将您想要的任何其他配置添加到搜索引擎中。具体而言，您可能希望执行以下操作：

• 选择外观和感觉。从默认的“叠加”布局更改为“仅结果**”，因为此选项意味着您的搜索结果将嵌入到搜索页面中，而不是显示在单独的框中。单击“保存”以保存更改。
  • 编辑默认结果链接行为，以便您网站的搜索结果不会在新标签页中打开。为此，请选择“搜索功能”-“高级”-“Web搜索设置”。在“链接目标”字段中，键入“_parent”。单击“保存”以保存更改。

添加搜索页面

设置搜索引擎后，您可以将该功能添加到您的网站：

1. 确保在“content/en/search.md”中有一个 Markdown 文件（如果需要，其他语言也有一个文件）来显示您的搜索结果。它只需要一个标题和“layout： search”，如以下示例所示：

   • Front matter:
   • toml
   • yaml
   • json

   +++
   title = "Search Results"
   layout = "search"
   +++

   ---
   title: Search Results
   layout: search
   ---

   {
       "title": "Search Results",
       "layout": "search"
   }

2. 将您的 Google 自定义搜索引擎 ID 添加到“hugo.toml”/“hugo.yaml”/“hugo.json”中的网站参数中。如果需要，您可以为每种语言添加不同的值。

   • Configuration file:
   • hugo.toml
   • hugo.yaml
   • hugo.json

   [params]
   # Google Custom Search Engine ID. Remove or comment out to disable search.
   gcs_engine_id = "011737558837375720776:fsdu1nryfng"

   params:
     gcs_engine_id: 011737558837375720776:fsdu1nryfng

   {
     "params": {
       "gcs_engine_id": "011737558837375720776:fsdu1nryfng"
     }
   }

禁用GCSE搜索

如果您没有为项目指定 Google 自定义搜索引擎 ID，并且未启用任何其他搜索选项，则搜索框不会显示在您的网站中。如果您使用示例站点中的默认“hugo.toml”并想要禁用搜索，只需注释掉或删除相关行即可。

Algolia 文档搜索

作为GCSE的替代方法，您可以使用[AlgoliaDocSearch]（https://docsearch.algolia.com），即对公共文档站点免费。Docsy 支持 Algolia DocSearch v3。

注册 Algolia DocSearch

填写https://docsearch.algolia.com/apply的表格。收到 Algolia DocSearch 后继续下一步项目的参数。

渴望测试 DocSearch？

Docsy 默认为 Algolia test-site 参数不提供任何信息。要启用对 Algolia 测试的搜索，请定义’params.search.algolia’，没有任何其他字段，如下所述。

配置 Algolia DocSearch

1. 确保禁用 [GCSE 搜索]（#disabling-gcse-search）。

2. 将项目的 Algolia DocSearch 参数添加到 ‘hugo.toml’/‘hugo.yaml’/‘hugo.json’，例如（使用 Algolia test 值）：

   • Configuration file:
   • hugo.toml
   • hugo.yaml
   • hugo.json

   [params.search.algolia]
   appId = "R2IYF7ETH7"
   apiKey = "599cec31baffa4868cae4e79f180729b"
   indexName = "docsearch"

   params:
     search:
       algolia:
         appId: R2IYF7ETH7
         apiKey: 599cec31baffa4868cae4e79f180729b
         indexName: docsearch

   {
     "params": {
       "search": {
         "algolia": {
           "appId": "R2IYF7ETH7",
           "apiKey": "599cec31baffa4868cae4e79f180729b",
           "indexName": "docsearch"
         }
       }
     }
   }

要了解有关 Algolia DocSearch V3 的更多信息，请参阅 [get-started]（https://docsearch.algolia.com/docs/DocSearch-v3）。

完成这些步骤后，应在网站。搜索结果显示为弹出窗口，因此您无需添加任何搜索结果搜索结果页面。

自定义 Algolia 模板

您可以通过创建以下模板文件：

• “head.html”使用的“layouts/partials/algolia/head.html”来加载 AlgoliaDocSearch 样式。它还会发出弃用警告’params.algolia_docsearch’。
• “scripts.html”使用的“layouts/partials/algolia/scripts.html”来加载和配置 Algolia DocSearch。将任一文件留空以禁用 Docsy 的实现。

使用 Lunr 进行本地搜索

[伦尔]（https://lunrjs.com/） 是一个基于 Javascript 的搜索选项，可让您为网站编制索引并使其可搜索，而无需外部服务器端搜索服务。这是一个不错的选择，特别是对于较小的或非公共网站。

要将 Lunr 搜索添加到您的 Docsy 网站：

1. 在 ‘hugo.toml’/‘hugo.yaml’/‘hugo.json’ 中启用本地搜索。

   • Configuration file:
   • hugo.toml
   • hugo.yaml
   • hugo.json

   [params]
   offlineSearch = true

   params:
     offlineSearch: true

   {
     "params": {
       "offlineSearch": true
     }
   }

2. 删除或注释掉 ‘hugo.toml’/‘hugo.yaml’/‘hugo.json’ 中的任何 GCSE ID，并确保 Algolia DocSearch 设置为 ‘false’，因为您只能启用一种类型的搜索。请参阅[禁用GCSE搜索]（#disabling-gcse-search）。

完成这些步骤后，将为您的网站启用本地搜索，并在使用搜索框时将结果显示在下拉列表中。

更改本地搜索结果的摘要长度

您可以通过在 ‘hugo.toml’/‘hugo.yaml’/‘hugo.json’ 中设置 ‘offlineSearchSummaryLength’ 来自定义摘要长度。

• Configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

#Enable offline search with Lunr.js
[params]
offlineSearch = true
offlineSearchSummaryLength = 200

params:
  offlineSearch: true
  offlineSearchSummaryLength: 200

{
  "params": {
    "offlineSearch": true,
    "offlineSearchSummaryLength": 200
  }
}

更改本地搜索的最大结果计数

您可以通过在 ‘hugo.toml’/‘hugo.yaml’/‘hugo.json’ 中设置 ‘offlineSearchMaxResults’ 来自定义最大结果计数。

• Configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

[params]
offlineSearch = true
offlineSearchMaxResults = 25

params:
  offlineSearch: true
  offlineSearchMaxResults: 25

{
  "params": {
    "offlineSearch": true,
    "offlineSearchMaxResults": 25
  }
}

更改本地搜索结果弹出窗口的宽度

搜索结果弹出窗口的宽度会根据内容自动变宽。

如果要限制宽度，请将以下 scss 添加到“assets/scss/_variables_project.scss”中。

.td-offline-search-results {
  max-width: 460px;
}

从本地搜索结果中排除页面

要从本地搜索结果中排除页面，请在每个页面的卷首添加“exclude_search： true”：

• Front matter:
• toml
• yaml
• json

+++
title = "Index"
weight = 10
exclude_search = true
+++

---
title: "Index"
weight: 10
exclude_search: true
---

{
  "title": "Index",
  "weight": 10,
  "exclude_search": true
}

5 - 文档版本控制

​ 根据您的项目的发布和版本控制，您可能希望让用户访问您的文档的先前版本。如何部署先前的版本取决于您。本页面介绍了 Docsy 中可用的功能，可用于在不同版本的文档之间提供导航，并在归档站点上显示信息横幅。

添加版本下拉菜单

​ 如果在 hugo.toml/hugo.yaml/hugo.json 中添加一些 [params.versions]，Docsy 主题将在顶级菜单中添加版本选择器下拉菜单。您可以指定每个版本的 URL 和名称，如下面的示例所示：

• Configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

# Add your release versions here
[[params.versions]]
  version = "master"
  url = "https://master.kubeflow.org"

[[params.versions]]
  version = "v0.2"
  url = "https://v0-2.kubeflow.org"

[[params.versions]]
  version = "v0.3"
  url = "https://v0-3.kubeflow.org"

params:
  versions:
    - version: master
      url: 'https://master.kubeflow.org'
    - version: v0.2
      url: 'https://v0-2.kubeflow.org'
    - version: v0.3
      url: 'https://v0-3.kubeflow.org'

{
  "params": {
    "versions": [
      {
        "version": "master",
        "url": "https://master.kubeflow.org"
      },
      {
        "version": "v0.2",
        "url": "https://v0-2.kubeflow.org"
      },
      {
        "version": "v0.3",
        "url": "https://v0-3.kubeflow.org"
      }
    ]
  }
}

​ 记得添加当前版本，以便用户可以导航回去！

​ 版本下拉菜单的默认标题为 Releases。要更改标题，请更改 hugo.toml/hugo.yaml/hugo.json 中的 version_menu 参数：

• Configuration file:
• hugo.toml
• hugo.yaml
• hugo.json

[params]
version_menu = "Releases"

params:
  version_menu: Releases

{
  "params": {
    "version_menu": "Releases"
  }
}

​ 如果将 version_menu_pagelinks 参数设置为 true，则版本下拉菜单中的链接指向其他版本中的当前页面，而不是主页面。如果文档在不同版本之间几乎没有变化，则此功能可能很有用。请注意，如果其他版本中不存在当前页面，则链接将被broken。

​ 您可以在navigation and search.指南中阅读有关 Docsy 菜单的更多信息。

在归档的文档站点上显示横幅

​ 如果为文档的早期版本创建了归档快照，则可以在归档的文档的每个页面顶部添加注释，以让读者知道他们正在查看未维护的快照，并向他们提供最新版本的链接。

​ 例如，请参见 Kubeflow v0.6 的归档文档：

图1：Kubeflow v0.6归档文档上的横幅

​ 要在文档站点上添加横幅，请在hugo.toml/hugo.yaml/hugo.json文件中进行以下更改：

1. 将archived_version参数设置为true：

   • Configuration file:
   • hugo.toml
   • hugo.yaml
   • hugo.json

   [params]
   archived_version = true

   params:
     archived_version: true

   {
     "params": {
       "archived_version": true
     }
   }

2. 将version参数设置为归档文档集的版本。例如，如果归档文档是版本0.1：

   • Configuration file:
   • hugo.toml
   • hugo.yaml
   • hugo.json

   [params]
   version = "0.1"

   params:
     version: 0.1

   {
     "params": {
       "version": "0.1"
     }
   }

3. 确保url_latest_version包含您想要指向读者的站点的URL。在大多数情况下，这应该是您文档的最新版本的URL：

   • Configuration file:
   • hugo.toml
   • hugo.yaml
   • hugo.json

   [params]
   url_latest_version = "https://your-latest-doc-site.com"

   params:
     url_latest_version: https://your-latest-doc-site.com

   {
     "params": {
       "url_latest_version": "https://your-latest-doc-site.com"
     }
   }

6 - Docsy简码

​使用Docsy的Hugo简码快速构建站点页面。

​ Hugo 允许你定义并使用 shortcodes，而不是从头编写所有站点页面。这些可重复使用的内容片段可以包含在你的页面中，通常使用 HTML 创建难以或不可能在简单的 Markdown 中实现的效果。简码还可以具有参数，例如，让你向花哨的简码文本框中添加自己的文本。除了 Hugo 的内置简码外，Docsy 还提供了一些自己的 简码，以帮助你构建页面。

简码分隔符

​ 如下所示，使用花括号样式的简码分隔符\{\{\<...\>\}\}告诉Hugo内部内容是HTML/纯文本，无需进一步处理。通过使用分隔符\{\{\%...\%\}\}，Hugo将把简码body视为Markdown。您可以在页面中使用这两种样式。

简码块

​ 本主题附带一组自定义页面块（Page Block ）简码，可用于组合着陆页面、About页面等。

​ 这些块共享一些通用参数：

• height

  块容器的预定义高度。可以是 min、med、max、full 或 auto 中的一个。将其设置为 full 将填充视口高度，这对于着陆页非常有用。

• color

  如果未提供，块将被分配一个主题调色板的颜色，但如果需要，您可以设置自己的颜色。您可以使用所有 Bootstrap 的颜色名称、主题颜色名称或灰度阴影。一些例子包括 primary、white、dark、warning、light、success、300、blue、orange。这将成为块的背景颜色，但文本颜色将适应以获得适当的对比度。

blocks/cover

​ blocks/cover简码创建填充页面顶部的着陆页类型块。

\{\{\< blocks/cover title="Welcome!" image_anchor="center" height="full" color="primary" \>\}\}
<div class="mx-auto">
 <a class="btn btn-lg btn-primary me-3 mb-4" href="\{\{\< relref "/docs" \>\}\}">
  Learn More <i class="fa-solid fa-circle-right ms-2"></i>
 </a>
 <a class="btn btn-lg btn-secondary me-3 mb-4" href="https://example.org">
  Download <i class="fa-brands fa-github ms-2 "></i>
 </a>
 <p class="lead mt-5">This program is now available in <a href="#">AppStore!</a></p>
 <div class="mx-auto mt-5">
  \{\{\< blocks/link-down color="info" \>\}\}
 </div>
</div>
\{\{\< /blocks/cover \>\}\}

请注意，上面提到的相关简码参数将具有合理的默认值，但为了完整性而包含在此处。

​ 要设置背景图像，请在该页面的Page Bundle中放置一个带有"background"单词的图像名称。例如，在我们的示例站点中，首页的封面块中的背景图像为featured-background.jpg，在同一目录中。

​ 有关可用图标，请参见Font Awesome。

blocks/lead

​ blocks/lead简码是一个简单的引导/标题块，具有居中的文本和向下箭头指向下一节。

\{\{\% blocks/lead color="dark" \%\}\}
TechOS is the OS of the future.

Runs on **bare metal** in the **cloud**!
\{\{\% /blocks/lead \%\}\}

blocks/section

​ blocks/section简码旨在作为通用内容容器使用。它有两种"口味（flavors）"，一种适用于一般内容，另一种则具有更适合包装水平特征章节的样式。

​ 下面的示例显示一个包含3个特征章节的章节。

\{\{\< blocks/section color="dark" type="row" \>\}\}
\{\{\% blocks/feature icon="fa-lightbulb" title="Fastest OS **on the planet**!" \%\}\}
The new **TechOS** operating system is an open source project. It is a new project, but with grand ambitions.
Please follow this space for updates!
\{\{\% /blocks/feature \%\}\}
\{\{\% blocks/feature icon="fa-brands fa-github" title="Contributions welcome!" url="https://github.com/gohugoio/hugo" \%\}\}
We do a [Pull Request](https://github.com/gohugoio/hugo/pulls) contributions workflow on **GitHub**. New users are always welcome!
\{\{\% /blocks/feature \%\}\}
\{\{\% blocks/feature icon="fa-brands fa-twitter" title="Follow us on Twitter!" url="https://twitter.com/GoHugoIO" \%\}\}
For announcement of latest features etc.
\{\{\% /blocks/feature \%\}\}
\{\{\< /blocks/section \>\}\}

blocks/feature

\{\{\% blocks/feature icon="fa-brands fa-github" title="Contributions welcome!" url="https://github.com/gohugoio/hugo" \%\}\}
We do a [Pull Request](https://github.com/gohugoio/hugo/pulls) contributions workflow on **GitHub**. New users are always welcome!
\{\{\% /blocks/feature \%\}\}

blocks/link-down

​ blocks/link-down简码创建导航链接到下一个章节。它旨在与其他块简码结合使用。

<div class="mx-auto mt-5">
 \{\{\< blocks/link-down color="info" \>\}\}
</div>

简码助手（helpers）

alert

​ alert简码创建一个警报块，可用于显示通知或警告。

{{% alert title="Warning" color="warning" %}}
This is a warning.
{{% /alert %}}

Renders to:

pageinfo

​ pageinfo 简码创建了一个文本框，您可以使用它来为页面添加横幅信息，例如告诉用户页面包含占位内容，内容已过时或记录了一个 beta 功能。

\{\{\% pageinfo color="primary" \%\}\}
This is placeholder content.
\{\{\% /pageinfo \%\}\}

渲染成：

imgproc

​ imgproc简码会在当前Page Bundle中查找图片，并根据给定的一组处理指令对其进行缩放。

\{\{\< imgproc spruce Fill "400x450" \>\}\}
Norway Spruce <i>Picea abies</i> shoot with foliage buds.
\{\{\< /imgproc \>\}\}

Use the syntax above if the inner content and/or the byline parameter of your shortcode is authored in markdown. In case of HTML content, use <> as innermost delimiters: {{< imgproc >}}<b>HTML</b> content{{< /imgproc >}}.

​ 上面的示例还添加了带有照片归属地的副标题。当使用来自WikiMedia等免费许可的插图时，大多数情况下需要一种方法来归属作者或许可证持有人。您可以在你的页面前置元数据中的页面资源中添加元数据。在此主题中，byline 参数通常用于此目的：

• Front matter:
• toml
• yaml
• json

+++
[[resources]]
src = "**spruce*.jpg"

[resources.params]
  byline = "*Photo*: Bjørn Erik Pedersen / CC-BY-SA"
+++

---

resources:

- src: "**spruce*.jpg"
  params:
    byline: "*Photo*: Bjørn Erik Pedersen / CC-BY-SA"

---

{
  "resources": [
    {
      "src": "**spruce*.jpg",
      "params": {
        "byline": "*Photo*: Bjørn Erik Pedersen / CC-BY-SA"
      }
    }
  ]
}

swaggerui

​ swaggerui 简码可以放置在任何使用 swagger 布局 的页面中；它使用任何 OpenAPI YAML 或 JSON 文件作为源来渲染 Swagger UI。该文件可以托管在任何位置，例如您站点的根/static folder。

• Front matter:
• toml
• yaml
• json

+++
title = "Pet Store API"
type = "swagger"
weight = 1
description = "Reference for the Pet Store API"
+++

{{<swaggerui src="/openapi/petstore.yaml">}}

---

title: "Pet Store API"
type: swagger
weight: 1
description: Reference for the Pet Store API
---

{{<swaggerui src="/openapi/petstore.yaml">}}

{
  "title": "Pet Store API",
  "type": "swagger",
  "weight": 1,
  "description": "Reference for the Pet Store API"
}

{{<swaggerui src="/openapi/petstore.yaml">}}

​ 您可以通过覆盖Swagger的CSS或通过编辑和编译Swagger UI dist自己来自定义Swagger UI的外观和感觉，并替换themes/docsy/static/css/swagger-ui.css。

redoc

​ redoc简码使用开源Redoc工具从OpenAPI YAML或JSON文件中渲染参考API文档。该文件可以托管在您喜欢的任何位置，例如在站点的根/static 文件夹中，但您也可以使用一个URL，例如：

---
title: "Pet Store API"
type: docs
weight: 1
description: Reference for the Pet Store API
---

\{\{\< redoc "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v2.0/yaml/petstore.yaml" \>\}\}

iframe

​ 使用此简码，您可以将外部内容作为内联框架（iframe）嵌入Docsy页面，参见：https://www.w3schools.com/tags/tag_iframe.asp

警告

​ 只有在服务器的 X-Frame-Options 未设置或明确允许被嵌入到您的站点时，才能嵌入外部内容。有关详细信息，请参见https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/X-Frame-Options。

​ 有几种工具可用于检查站点是否可以通过iframe嵌入，例如：https://gf.dev/x-frame-options-test。请注意，当此测试显示"Couldn’t find the X-Frame-Options header in the response headers.“时，您可以嵌入它，但是当测试显示"Great! X-Frame-Options header was found in the HTTP response headers as highlighted below.“时，除非已明确启用了您的站点，否则您不可以嵌入它。

Tabbed panes 选项卡式窗格

​ 在编写内容时，有时非常有用的是选项卡式窗格。一个常见的用例是显示多个语法突出显示的代码块，这些代码块展示了同一问题在不同编程语言中的解决方法。例如，下面的选项卡式窗格显示了通常在学习新编程语言时编写的Hello world！程序的语言特定变体：

• C
• C++
• Go
• Java
• Kotlin
• Lua
• PHP
• Python
• Ruby
• Scala

# include <stdio.h>
# include <stdlib.h>

int main(void)
{
  puts("Hello World!");
  return EXIT_SUCCESS;
}

# include <iostream>

int main()
{
  std::cout << "Hello World!" << std::endl;
}

package main
import "fmt"
func main() {
  fmt.Printf("Hello World!\n")
}

class HelloWorld {
  static public void main( String args[] ) {
    System.out.println( "Hello World!" );
  }
}

fun main(args : Array<String>) {
    println("Hello, world!")
}

print "Hello world"

<?php
echo 'Hello World!';
?>

print("Hello World!")

puts "Hello World!"

object HelloWorld extends App {
  println("Hello world!")
}

​ Docsy模板提供了两个简码tabpane和tab，让您轻松创建选项卡式窗格。要了解如何使用它们，请查看以下代码块，该代码块渲染为右对齐的窗格，其中一个选项卡被禁用，另外三个选项卡处于活动状态：

\{\{\< tabpane text=true right=true \>\}\}
  \{\{\% tab header="**Languages**:" disabled=true /\%\}\}
  \{\{\% tab header="English" lang="en" \%\}\}
  ![Flag United Kingdom](flags/uk.png)
  Welcome!
  \{\{\% /tab \%\}\}
  \{\{\< tab header="German" lang="de" \>\}\}
    <b>Herzlich willkommen!</b>
    <img src="flags/de.png" alt="Flag Germany" style="float: right; padding: 0 0 0 0px">
  \{\{\< /tab \>\}\}
  \{\{\% tab header="Swahili" lang="sw" \%\}\}
  ![Flag Tanzania](flags/tz.png)
  **Karibu sana!**
  \{\{\% /tab \%\}\}
\{\{\< /tabpane \>\}\}

​ 这段代码转换为下面的右对齐选项卡窗格，显示英语、德语或斯瓦希里语的Welcome!问候：

• Languages:
• English
• German
• Swahili

Welcome!

Herzlich willkommen!

Karibu sana!

简码详细信息

​ 选项卡式窗格使用两个简码实现：

• tabpane 简码是选项卡的容器元素。该简码可以包含可选的命名参数 lang、highlight 和 right。可选参数 lang 和 highlight 的值会作为 Hugo 内置函数 highlight 的第二个 LANG 和第三个 OPTIONS 参数传递，该函数用于渲染各个选项卡中的代码块。如果您想要右对齐选项卡，请指定 right=true。如果选项卡的标题文本等于选项卡代码块中使用的语言（如上面的第一个选项卡窗格示例），您可以在周围的 tabpane 简码中指定 langEqualsHeader=true。然后，各个选项卡的标题文本将自动设置为相应选项卡的 lang 参数。

• 各种选项卡简码代表您想要显示的选项卡。对于每个选项卡，通过指定命名参数 header 来设置选项卡的标题文本。如果header参数是您选项卡简码中唯一的参数，则可以将标题设置为未命名参数，例如 { tab "My header" }} … {{ /tab }}。如果您的选项卡简码没有任何参数，则选项卡的header 将默认为Tab n。要将窗格分为左对齐和右对齐的选项卡组，请在分隔选项卡中指定 right=true。通过多次设置 right=true，您甚至可以渲染多个选项卡组。通过指定参数 disabled=true 可以禁用选项卡。对于启用的选项卡，有两种内容显示模式，代码表示和文本表示：

  • 默认情况下，选项卡的内容将渲染为代码块。为了获得适当的语法高亮显示，请为每个选项卡指定命名参数 lang，并可选地指定参数 highlight。在父选项卡窗格简码中设置的参数将被覆盖。
  • 如果您的选项卡内容应该渲染为具有不同样式和可选图像的文本，请将 text=true 作为tabpane （或tab）的参数。如果您的内容是 Markdown，请使用百分号 % 作为选项卡简码的最外层分隔符，您的标记应如下所示：\{\{\% tab \%\}\}Your **markdown** content\{\{\% /tab \%\}\}。对于 HTML 内容，请使用方括号 <> 作为最外层分隔符：\{\{\< tab \>\}\}Your <b>HTML</b> content\{\{\< /tab \>\}\}。

信息

​ 默认情况下，所选tab（选项卡） 的语言将存储并在不同的浏览器会话之间保留。如果选项卡内的内容长度差异很大，则在切换选项卡时可能会导致不必要的滚动。要禁用此不必要的行为，请在tabpane简码中指定 persistLang=false。

Card panes 卡片窗格

​ 在编写内容时，将类似的文本块或代码片段放在类似卡片的元素上，可以让它们可选地并排呈现，这在某些情况下非常有用。下面是一个样本卡片组，展示了美国的前四位总统，我们来演示一下这个功能：

George Washington

*1732     †1799

President: 1789 – 1797

John Adams

* 1735     † 1826

President: 1797 – 1801

Thomas Jefferson

* 1743     † 1826

President: 1801 – 1809

James Madison

* 1751     † 1836

President: 1809 – 1817

​ Docsy 支持通过不同的简码创建此类卡片窗格：

• cardpane 简码是用来包含不同卡片的容器元素。
• card 简码代表一个单独的卡片，每个简码代表一个独立的卡片。虽然卡片通常会出现在卡片组内，但一个单独的卡片也可以单独呈现。card 简码可以包含文本、图片或任何其他任意类型的 Markdown 或 HTML 标记作为内容。如果你的内容是编程代码，建议使用 card-code 简码，这是一种具有代码高亮和其他可选功能（如行号、某些行的高亮等）的特殊卡片。

简码card（用于文本、图像等）

​ 如上所述，卡片可以使用 card 或 card-code 简码之一进行编码。如果您的内容是除了编程代码以外的任何类型的文本，请使用通用的 card 简码。以下代码示例演示如何编码card 元素：

\{\{\< card header="**Imagine**" title="Artist and songwriter: John Lennon" subtitle="Co-writer: Yoko Ono"
          footer="![SignatureJohnLennon](https://server.tld/…/signature.png 'Signature John Lennon')"\>\}\}
Imagine there's no heaven, It's easy if you try<br/>
No hell below us, above us only sky<br/>
Imagine all the people living for today…

…
\{\{\< /card \>\}\}

​ 此代码转换为下面的左侧的卡片，显示 John Lennon 著名歌曲 Imagine 的歌词。右侧的第二个说明性card 元素指示并解释了card 的各个组成部分：

… {{}}

This code translates to the left card shown below, showing the lyrics of John Lennon's famous song `Imagine`. A second explanatory card element to the right indicates and explains the individual components of a card:

<div class="td-card-group card-group p-0 mb-4">
<div class="td-card card border me-4">
<div class="card-header">
      <strong>Imagine</strong>
    </div>
<div class="card-body">
    <h5 class="card-title">
        Artist and songwriter: John Lennon</h5>
    <h6 class="card-title ms-2 text-body-secondary">
        Co-writer: Yoko Ono</h6>
    <p class="card-text">
        
Imagine there's no heaven, It's easy if you try<br/>
No hell below us, above us only sky<br/>
Imagine all the people living for today…

Imagine there's no countries, it isn't hard to do<br/>
Nothing to kill or die for, and no religion too<br/>
Imagine all the people living life in peace…

Imagine no possessions, I wonder if you can<br/>
No need for greed or hunger - a brotherhood of man<br/>
Imagine all the people sharing all the world…

You may say I'm a dreamer, but I'm not the only one<br/>
I hope someday you'll join us and the world will live as one
</p>
      </div>
  <div class="card-footer">
      <img alt="SignatureJohnLennon" src="https://upload.wikimedia.org/wikipedia/commons/thumb/5/51/Firma_de_John_Lennon.svg/320px-Firma_de_John_Lennon.svg.png" title="Signature John Lennon"></div>
  </div>

<div class="td-card card border me-4">
<div class="card-header">
      <strong>Header</strong>: specified via named parameter <code>Header</code>
    </div>
<div class="card-body">
    <h5 class="card-title">
        <strong>Card title</strong>: specified via named parameter <code>title</code></h5>
    <h6 class="card-title ms-2 text-body-secondary">
        <strong>Card subtitle</strong>: specified via named parameter <code>subtitle</code></h6>
    <p class="card-text">
        <p><strong>Content</strong>: inner content of the shortcode, this may be plain text or formatted text, images, videos, … . If your content is markdown, use the percent sign <code>%</code> as outermost delimiter of your <code>card</code> shortcode, your markup should look like <code>{{% card %}}Your **markdown** content{{% /card %}}</code>. In case of HTML content, use square brackets <code>&lt;&gt;</code> as outermost delimiters: <code>{{&lt; card &gt;}}Your &lt;b&gt;HTML&lt;/b&gt; content{{&lt; /card &gt;}}</code></p>
</p>
      </div>
  <div class="card-footer">
      <strong>Footer</strong>: specified via named parameter <code>footer</code></div>
  </div>

</div>



​ 虽然卡片的主要内容取自 `card` 简码的内部标记，但可选元素 `footer`、`header`、`title` 和 `subtitle` 都作为简码的命名参数指定。

### 简码`card-code`（用于编程代码） 

​ 如果您想在卡片上显示编程代码，可以使用专门的`card-code` 简码。下面的示例演示了如何用C编写著名的`Hello world!`应用程序的卡片元素：

```go-html-template
\{\{\< card-code header="**C**" lang="C" \>\}\}
#include <stdio.h>
#include <stdlib.h>

int main(void)
{
  puts("Hello World!");
  return EXIT_SUCCESS;
}
\{\{\< /card-code \>\}\}

​ 这段代码将转换为下面的卡片：

# include <stdio.h>
# include <stdlib.h>

int main(void)
{
  puts("Hello World!");
  return EXIT_SUCCESS;
}

​ card-code 简码可以可选地包含lang和/或highlight命名参数。这些可选参数的值作为第二个LANG和第三个OPTIONS参数传递给Hugo的内置highlight函数，该函数用于渲染在卡片上呈现的代码块。

卡片组

​ 将两个或多个卡片并排显示可以通过将它们放在cardpane简码的开放和关闭元素之间轻松实现。卡片组的一般标记与选项卡窗格的标记非常相似：

\{\{\< cardpane \>\}\}
  \{\{\< card header="Header card 1" \>\}\}
    Content card 1
  \{\{\< /card \>\}\}
  \{\{\< card header="Header card 2" \>\}\}
    Content card 2
  \{\{\< /card \>\}\}
  \{\{\< card header="Header card 3" \>\}\}
    Content card 3
  \{\{\< /card \>\}\}
\{\{\< /cardpane \>\}\}

​ 与选项卡（tabs）不同，卡片（cards ）是并排呈现的。这尤其有用，如果您想在两个卡片上比较不同的编程技术（传统 vs. 现代），就像上面的示例演示的那样：

File[] hiddenFiles = new File("directory_name")
  .listFiles(new FileFilter() {
    public boolean accept(File file) {
      return file.isHidden();
    }
  });

File[] hiddenFiles = new File("directory_name")
  .listFiles(File::isHidden);

包含外部文件

​ 有时候有一些内容对多个文档都是相关的，或者是存储在一个不一定是文档的文件中。对于这样的情况，readfile 简码允许您将外部文件的内容导入到文档中。

重用文档

​ 如果您想在多个文档中重复使用一些内容，可以将该内容编写在一个单独的文件中，然后在需要时包含它。

​ 例如，假设您有一个名为installation.md的文件，其内容如下：

## Installation

\{\{\% alert title="Note" color="primary" \%\}\}
Check system compatibility before proceeding.
\{\{\% /alert \%\}\}

1.  Download the installation files.

1.  Run the installation script

    `sudo sh install.sh`

1.  Test that your installation was successfully completed.

​ 您可以将此部分导入到另一个文档中：

The following section explains how to install the database:

\{\{\% readfile "installation.md" \%\}\}

​ 这将渲染出好像指令在父文档中一样。导入文件包含简码时需要 Hugo v0.101.0+ 才能正确被渲染。

The following section explains how to install the database:

Installation

Check system compatibility before proceeding.

1. Download the installation files.

2. Run the installation script

   sudo sh install.sh

3. Test that your installation was successfully completed.

​ 该参数是该文件的相对路径。仅支持在父文件的工作目录下的相对路径。

​ 对于工作目录之外的文件，可以使用以 / 开头的绝对路径。根目录是 /content 文件夹。

包含代码文件

​ 假设您有一个包含多个代码示例的includes文件夹，您希望将其用作文档的一部分。您可以使用readfile并带有一些额外的参数：

To create a new pipeline, follow the next steps:

1.  Create a configuration file `config.yaml`:

    \{\{\< readfile file="includes/config.yaml" code="true" lang="yaml" \>\}\}

2.  Apply the file to your cluster `kubectl apply config.yaml`

​ 该代码自动读取includes/config.yaml的内容并将其插入到文档中。渲染后的文本如下所示：

To create a new pipeline, follow the next steps:

1. Create a configuration file config.yaml:

   apiVersion: tekton.dev/v1beta1
       kind: Task
       metadata:
         name: hello
       spec:
         steps:
           - name: echo
             image: alpine
             script: |
               #!/bin/sh
               echo "Hello World"          
       

2. Apply the file to your cluster kubectl apply config.yaml

​ 该"file"参数是文件的相对路径。仅支持在父文件的工作目录下的相对路径。

​ 对于工作目录之外的文件，可以使用以 / 开头的绝对路径。根目录是 /content 文件夹。

错误报告

​ 如果该简码无法找到指定的文件，则该简码会抛出编译错误。

​ 在下面的示例中，如果无法找到includes/deploy.yml文件，Hugo会抛出编译错误：

\{\{\< readfile file="includes/deploy.yaml" code="true" lang="yaml" \>\}\}

​ 或者，Hugo可以在呈现的页面上显示一条消息，而不是抛出编译错误。添加draft="true"参数。例如：

\{\{\< readfile file="includes/deploy.yaml" code="true" lang="yaml" draft="true" \>\}\}

条件文本

​ conditional-text 简码允许您根据配置文件中设置的 buildCondition 参数的值来显示或隐藏内容的某些部分。如果您正在从相同的源生成不同的构建，例如使用不同的产品名称，那么这将非常有用。这个简码帮助您处理这些构建之间的小差异。

\{\{\% conditional-text include-if="foo" \%\}\}
This text appears in the output only if `buildCondition = "foo" is set in your config file`.
\{\{\% /conditional-text \%\}\}
\{\{\% conditional-text exclude-if="bar" \%\}\}
This text does not appear in the output if `buildCondition = "bar" is set in your config file`.
\{\{\% /conditional-text \%\}\}

​ 如果您正在使用此简码，请注意，在求值条件时，子字符串匹配也将被视为匹配。这意味着，如果您设置了 include-if="foobar"，而 buildcondition = "foo"，则匹配！

7 - Logo和图片

添加您的logo

​ 默认情况下，Docsy在导航栏的开头即极左处显示一个站点logo。将您的项目的SVG logo放在assets/icons/logo.svg中。这将覆盖主题中默认的Docsy logo。