文章头部

文章头部(front matter)是每个文件顶部用三点划线包裹的 YAML 代码, 它为我们的内容提供了重要的管理选项。例如:文章头部允许我们确保现有链接对于已经完全移动或删除的页面继续有效。 本页说明了 Istio 中文章头部目前可用的功能。

下面是一个文章头部的示例,其中所有必填字段都由占位符填充:

---
title: <title>
description: <description>
weight: <weight>
keywords: [<keyword1>,<keyword2>,...]
aliases:
    - <previously-published-at-this-URL>
---

您可以复制上面的示例,并在您的页面中使用相应值替换所有占位符。

必填字段

下表列举了所有的必填字段及其说明:

字段说明
title该页面的标题。
description对该页面内容的一个简单描述。
weight该页面相对于当前目录中其他页面的顺序。
keywords页面上的关键字。Hugo 根据此列表在页面末尾生成“相关内容”链接。
aliases页面以前发布过的 URL。有关此字段的详细信息,请参见下面的重命名、移动或删除页面

重命名、移动或删除页面

当您移动或完全删除页面时,必须确保指向这些页面的现有链接继续有效。 文章头部中的 aliases 字段可帮助您满足此要求。在移动或删除页面之前, 将现有路径添加到 aliases 字段中。Hugo 为我们的用户实现了从旧 URL 到新 URL 的自动重定向。

目标页面(您想让用户访问的页面)上,将原始页面<path> 添加到文章头部中,如下所示:

aliases:
    - <path>

例如,您可以在以前的 /zh/help/faq 下找到我们的 FAQ 页面。 为了使用户更方便的找到 FAQ 页面,我们将该页面上移了一个级别至 /zh/faq/, 并对文章头部做了以下更改:

---
title: Frequently Asked Questions
description: Questions Asked Frequently.
weight: 13
aliases:
    - /zh/help/faq
---

上面的更改允许所有用户通过 https://istio.io/zh/faq/ 或者 https://istio.io/zh/help/faq/ 都能访问到 FAQ 页面。

不仅是一个,该字段支持多个重定向,例如:

---
title: Frequently Asked Questions
description: Questions Asked Frequently.
weight: 13
aliases:
    - /zh/faq
    - /zh/faq2
    - /zh/faq3
---

可选字段

Hugo 支持非常多的文章头部字段,而此页面仅列举了在 istio.io 中实现的字段。

下表列举了最常用的可选字段:

字段描述
linktitle短标题,常用于链接到页面。
subtitle主标题下方显示的副标题。
icon标题旁边显示图标的路径。
draft如果为 true,该页面不会出现在网站中。
skip_byline如果为 true,Hugo 不会在主标题下显示下划线。
skip_seealso如果为 true,Hugo 不会为该页面生成"相关内容"链接。

一些文章头部字段可用于控制自动生成的目录(ToC)。下表列举了这些字段并说明了如何使用:

字段描述
skip_toc如果为 true,Hugo 不会为该页面生成目录。
force_inline_toc如果为 true,Hugo 会强制在文本中插入自动生成的目录,而不是右侧的边栏。
max_toc_level设置目录(ToC)中使用的标题级别。值可以从 2 到 6。
remove_toc_prefixHugo 从目录中每个条目的前缀中删除此字符串。

某些文章头部字段仅适用于所谓的捆绑页面。您可以辨别捆绑页面, 因为它们的文件名都是以下划线 _ 开头,例如:_index.md。在 Istio 中, 我们使用捆绑页面作为我们的部分落地页。下表列举了与捆绑页面相关的文章头部字段。

字段描述
skip_list如果为 true,Hugo 不会自动生成该部分页面的内容块。
simple_list如果为 true,Hugo 使用一个简单列表列出该部分页面的自动生成内容。
list_below如果为 true,Hugo 会将自动生成的内容追加到手动编写的内容后面。
list_by_publishdate如果为 true,Hugo 会按照 publishdate 而不是 weight,对自动生成的内容进行排序。

类似的,某些文章头部字段仅适用于博客文章。下表列举了这些字段:

字段描述
publishdate博客的原始发布日期
last_update最近一次进行重大修改的日期
attribution可选的,作者的姓名
twitter可选的,作者的 Twitter
target_release此博客内容中所使用的 Istio 版本。通常,该值是在创作或更新该博客时,当时最新的主要 Istio 版本。
这些信息有用吗?
您是否有更多建议和改进意见?

感谢您的反馈!