使用短代码

9 分钟阅读

Hugo 短代码是具有特定语法的特殊占位符，您可以将其添加到内容中以创建动态内容体验，例如选项卡、图像和图标、到其他页面的链接以及特殊的内容布局。

此页面解释了可用的短代码以及如何将其用于您的内容。

添加图像

将图像文件放置在与使用它们的 Markdown 文件相同的目录中。为了简化本地化并增强可访问性，首选的图像格式是 SVG。以下示例显示了添加图像所需的短代码及其必需字段

{{< image width="75%" ratio="45.34%"
    link="./<image.svg>"
    caption="<The caption displayed under the image>"
    >}}

link 和 caption 字段是必需的，但短代码也支持可选字段，例如

{{< image width="75%" ratio="45.34%"
    link="./<image.svg>"
    alt="<Alternate text used by screen readers and when loading the image fails>"
    title="<Text that appears on mouse-over>"
    caption="<The caption displayed under the image>"
    >}}

如果您不包含 title 字段，Hugo 将使用 caption 中设置的文本。如果您不包含 alt 字段，Hugo 将使用 title 中的文本，或者如果 title 也未定义，则使用 caption 中的文本。

width 字段设置图像相对于周围文本的大小，默认值为 100%。

ratio 字段设置图像相对于其宽度的高度。Hugo 会自动计算文件夹中图像文件的此值。但是，您必须手动计算外部图像的值。将 ratio 的值设置为 ([图像高度]/[图像宽度]) * 100。

添加图标

您可以使用以下内容将常用图标嵌入到内容中

{{< warning_icon >}}
{{< idea_icon >}}
{{< checkmark_icon >}}
{{< cancel_icon >}}
{{< tip_icon >}}

图标在文本中呈现。例如, , , 和.

添加指向其他页面的链接

Istio 文档根据其目标支持三种类型的链接。每种类型使用不同的语法来表达目标。

外部链接。这些是到 Istio 文档或 Istio GitHub 存储库外部页面的链接。使用标准 Markdown 语法包含 URL。在引用 Internet 上的文件时，请使用 HTTPS 协议，例如
```
[Descriptive text for the link](https://mysite/myfile.html)
```
相对链接。这些链接指向当前文件同一级别的页面或层次结构中更低级别的页面。相对链接的路径以句点 . 开头，例如
```
[This links to a sibling or child page](./sub-dir/child-page.html)
```
绝对链接。这些链接指向当前页面层次结构外部但在 Istio 网站内的页面。绝对链接的路径以斜杠 / 开头，例如
```
[This links to a page on the about section](/about/page/)
```

无论类型如何，链接都不会指向包含内容的 index.md 文件，而是指向包含它的文件夹。

添加指向 GitHub 上内容的链接

有几种方法可以引用 GitHub 上的内容或文件

{{< github_file >}} 是您如何引用 GitHub 中的单个文件（例如 yaml 文件）的方法。此短代码生成指向 https://raw.githubusercontent.com/istio/istio* 的链接，例如
```
[liveness]({{< github_file >}}/samples/health-check/liveness-command.yaml)
```
{{< github_tree >}} 是您如何引用 GitHub 中的目录树的方法。此短代码生成指向 https://github.com/istio/istio/tree* 的链接，例如
```
[httpbin]({{< github_tree >}}/samples/httpbin)
```
{{< github_blob >}} 是您如何引用 GitHub 源代码中的文件的方法。此短代码生成指向 https://github.com/istio/istio/blob* 的链接，例如
```
[RawVM MySQL]({{< github_blob >}}/samples/rawvm/README.md)
```

上述短代码根据文档当前目标分支生成指向 GitHub 中相应分支的链接。要验证当前目标分支，可以使用 {{< source_branch_name >}} 短代码获取当前目标分支的名称。

版本信息

要通过从网站检索当前版本在您的内容中显示当前 Istio 版本，请使用以下短代码

{{< istio_version >}}，呈现为 1.24
{{< istio_full_version >}}，呈现为 1.24.0

词汇表术语

当您在页面中引入专门的 Istio 术语时，贡献的补充验收标准要求您将该术语包含在词汇表中，并使用 {{< gloss >}} 短代码标记其第一个实例。短代码生成特殊的渲染，邀请读者点击该术语以获取包含定义的弹出窗口。例如

The Istio component that programs the {{<gloss>}}Envoy{{</gloss>}} proxies, responsible for service discovery, load balancing, and routing.

呈现如下

Istio 组件，用于对 Envoy 代理进行编程，负责服务发现、负载平衡和路由。

如果您在文本中使用该术语的变体，您仍然可以使用此短代码包含带有定义的弹出窗口。要指定替换，只需在短代码中包含词汇表条目即可。例如

{{<gloss envoy>}}Envoy's{{</gloss>}} HTTP support was designed to first and foremost be an HTTP/2 multiplexing proxy.

使用 envoy 词汇表条目的弹出窗口呈现如下

Envoy's HTTP 支持旨在首先成为 HTTP/2 多路复用代理。

旁注

要强调内容块，您可以将其格式化为警告、想法、提示或引用。所有标注都使用非常类似的短代码

{{< warning >}}
This is an important warning
{{< /warning >}}

{{< idea >}}
This is a great idea
{{< /idea >}}

{{< tip >}}
This is a useful tip from an expert
{{< /tip >}}

{{< quote >}}
This is a quote from somewhere
{{< /quote >}}

上述短代码呈现如下

谨慎使用标注。每种类型的标注都有其特定的用途，过度使用会抵消其预期用途和效果。通常，您不应该在每个内容文件中包含多个标注。

使用样板文本

要重用内容，同时保持其单一来源，请使用样板短代码。要将样板文本嵌入到任何内容文件中，请使用 boilerplate 短代码，如下所示

{{< boilerplate example >}}

上述短代码包含来自 /content/en/boilerplates/ 文件夹中 example.md Markdown 文件的以下内容

这是一些样板 markdown 文本。

A sample nested text block in a boilerplate.

该示例显示您需要包含 Markdown 文件的文件名，其中包含您希望在当前位置插入的内容。您可以在 /content/en/boilerplates 目录中找到现有的样板文件。

使用选项卡

要显示具有多个选项或格式的内容，请使用选项卡集和选项卡。例如

不同平台的等效命令
不同语言的等效代码示例
替代配置

要插入选项卡内容，请组合使用 tabset 和 tabs 短代码，例如

{{< tabset category-name="platform" >}}

{{< tab name="One" category-value="one" >}}
ONE
{{< /tab >}}

{{< tab name="Two" category-value="two" >}}
TWO
{{< /tab >}}

{{< tab name="Three" category-value="three" >}}
THREE
{{< /tab >}}

{{< /tabset >}}

上述短代码生成以下输出

一

每个选项卡的 name 属性的值包含显示的选项卡文本。在每个选项卡中，您可以使用正常的 Markdown 内容，但选项卡具有限制。

category-name 和 category-value 属性是可选的，并且使选定的选项卡在访问页面的过程中保持不变。例如，访问者选择一个选项卡，并且他们的选择会使用给定的名称和值自动保存。如果多个选项卡集使用相同的类别名称和值，则其选择会在页面之间自动同步。当站点中存在许多包含相同类型格式的选项卡集时，这尤其有用。

例如，多个选项卡集可以提供 GCP、BlueMix 和 AWS 的选项。您可以将 category-name 属性的值设置为 environment，并将 category-value 属性的值设置为 gcp、bluemix 和 aws。然后，当读者在一个页面中选择一个选项卡时，他们的选择将自动贯穿整个网站上的所有选项卡集。

选项卡限制

您可以在选项卡中使用几乎所有 Markdown，但以下情况除外

标题。选项卡中的标题显示在目录中，但点击目录中的链接不会自动选择选项卡。
嵌套选项卡集。不要嵌套选项卡集。这样做会导致糟糕的阅读体验，并可能造成严重的混淆。

使用横幅和贴纸

为了宣传即将举行的活动或宣传新内容，您可以自动按顺序将时间敏感的横幅和贴纸插入生成的站点中。我们为促销活动实现了以下短代码

倒计时贴纸：它们显示重大活动之前还剩多少时间。例如：“距离 3 月 30 日的 ServiceMeshCon 还有 37 天”。贴纸对读者在活动之前的视觉效果有一定的影响，应谨慎使用。
横幅：它们向读者显示有关即将发生、正在发生或已经发生的重大事件的重要消息。例如“Istio 1.5 已发布，立即下载！”或“3 月 30 日加入我们参加 ServiceMeshCon”。横幅是在活动期间向读者显示的全屏片段。

要创建横幅和贴纸，请在 events/banners 或 events/stickers 文件夹中创建 Markdown 文件。每个事件创建一个 Markdown 文件，并使用专用的前置 matter 字段来控制其行为。下表解释了可用的选项

字段	描述
`title`	事件的名称。这不会在网站上显示，它旨在用于诊断消息。
`period_start`	以 `YYYY-MM-DD` 格式开始显示项目的起始日期。除了日期之外，这也可以是值 `latest_release`，然后使用最新的已知 Istio 版本作为起始日期。当创建标语“Istio x.y.z 刚刚发布”时，这很有用。
`period_end`	以 `YYYY-MM-DD` 格式显示项目的最后日期。此值与下面的 `period_duration` 互斥。
`period_duration`	向用户显示项目的天数。此值与上面的 `period_end` 互斥。
`max_impressions`	在事件期间向用户显示内容的次数。值为 3 表示用户在期间访问的前三个页面将显示内容，并且在后续页面加载时内容将被隐藏。值为 0 或完全省略该字段会导致在期间的所有页面访问中显示内容。
`timeout`	内容在给定页面上对用户可见的时间量。经过这么长时间后，该项目将从页面中删除。
`link`	您可以指定一个 URL，它会将整个项目变成一个可点击的目标。当用户点击该项目时，该项目将不再显示给用户。此处可以使用特殊值 `latest_release` 来引入指向当前版本公告页面的链接。