使用 Shortcode

Hugo 的 Shortcode 是具有特定语法的特殊占位符，您可以将其添加到内容中以创建动态内容体验， 例如选项卡、图片、图标、指向另一个页面的链接以及特殊内容布局。

本页面介绍了可用的 Shortcode 及其用法。

添加图片

将图片文件跟 Markdown 文件放在相同的目录。为了增强其可读性，以及方便本地化， 首选的图片格式是 SVG。下面的示例展示了添加带有图片的 Shortcode，所需的必填字段：

  1. {{< image width="75%" ratio="45.34%"
  2.     link="./<image.svg>"
  3.     caption="<图片下方显示的标题>"
  4.     >}}

link 和 caption 字段是必填字段，这种 Shortcode 也支持可选字段，例如：

  1. {{< image width="75%" ratio="45.34%"
  2.     link="./<image.svg>"
  3.     alt="<使用屏幕阅读器且图片加载失败时使用的备用文本>"
  4.     title="<鼠标悬停在图片上时显示的文本>"
  5.     caption="<图片下方显示的标题>"
  6.     >}}

如果您没有填写 alt 字段，Hugo 会自动使用 title 的文本。如果您没有填写 title 字段， Hugo 会自动使用 caption 的文本。

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

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

添加图标

您可以将通用图标嵌入到具有以下内容的内容中：

  1. {{< warning_icon >}}
  2. {{< idea_icon >}}
  3. {{< checkmark_icon >}}
  4. {{< cancel_icon >}}
  5. {{< tip_icon >}}

图标会呈现在文本中，例如：使用 Shortcode - 图1、使用 Shortcode - 图2、 使用 Shortcode - 图3、使用 Shortcode - 图4 以及 使用 Shortcode - 图5。

添加指向其它页面的链接

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

  • 外部链接：用于指向 Istio 在 GitHub 的仓库，或者其它的站外链接。使用标准的 Markdown 语法表示 URL。当您引用的文件在互联网上时，请尽量使用 HTTPS 协议，例如：

    1. [链接的描述文本](https://mysite/myfile.html)

  • 相对链接：用于指向与当前文件位于同一级，或者更深层级的目标。相对链接以点 . 开头，例如：

    1. [链接到同级或子页面](./sub-dir/child-page.html)

  • 绝对链接：用于指向当前页面之外，但位于 Istio 站点之内页面的目标。 绝对路径以斜线 / 开头，例如：

    1. [链接到关于页面](/zh/about/)

无论使用何种类型，链接都不会指向内容的 index.md 文件，而是指向包含 index.md 的那个目录。

添加指向 GitHub 内容的链接

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

  • {{< github_file >}}，用于引用 GitHub 中的单个文件（例如 yaml 文件）。 该 Shortcode 会渲染为 https://raw.githubusercontent.com/istio/istio*，例如：

    1. [liveness]({{< github_file >}}/samples/health-check/liveness-command.yaml)

  • {{< github_tree >}}，用于引用 GitHub 中的一个目录。该 Shortcode 会渲染为 https://github.com/istio/istio/tree*，例如：

    1. [httpbin]({{< github_tree >}}/samples/httpbin)

  • {{< github_blob >}}，用于引用 GitHub 中的单个文件，该 Shortcode 会渲染为 https://github.com/istio/istio/blob*，例如：

    1. [RawVM MySQL]({{< github_blob >}}/samples/rawvm/README.md)

上面的 Shortcode 会根据文档当前的目标分支，生成指向 GitHub 中对应分支的链接。 要查看当前目标分支的名称，可以使用 {{< source_branch_name >}} Shortcode 来获取当前目标分支的名称。

版本信息

想要通过从网站检索，在您的内容中显示 Istio 的当前版本，请使用以下这些 Shortcode：

  • {{< istio_version >}}，渲染结果为：1.21
  • {{< istio_full_version >}}，渲染结构为：1.21.0

术语表

当在某个页面中提及一个 Istio 术语时，贡献补充条款要求您将该术语包含在 glossary 中， 并在本页第一次出现这个术语时使用 Shortcode {{< gloss >}} 进行标记。这种 Shortcode 会生成一个特殊的渲染效果，读者点击该术语，可以在弹出的窗口中获取该术语的定义。例如：

  1. Istio 里的组件通过控制 <span class="term" data-title="Envoy" data-body="&lt;p&gt;Envoy 是在 Istio 里使用的高性能代理，用于为所有&lt;a href=&#34;/zh/docs/reference/glossary/#service-mesh&#34;&gt;服务网格&lt;/a&gt;里的&lt;a href=&#34;/zh/docs/reference/glossary/#service&#34;&gt;服务&lt;/a&gt;调度进出的流量。
  2. &lt;a href=&#34;https://www.envoyproxy.io/&#34;&gt;了解更多关于 Envoy&lt;/a&gt;。&lt;/p&gt;
  3. ">Envoy</span> 代理，实现服务发现、负载均衡和路由分发。

渲染结果如下：

Istio 里的组件通过控制 Envoy 代理，实现服务发现、负载均衡和路由分发。

如果您想在您的文本中使用该术语的其它形式，您依然可以使用该 Shortcode。 要修改显示文本，只需在 Shortcode 中包含对应的术语条目即可。例如：

  1. {{<gloss envoy>}}Envoy{{</gloss>}} 的 HTTP 支持首先被设计为 HTTP/2 多路复用代理。

术语 envoy 定义的渲染结果如下：

Envoy 的 HTTP 支持首先被设计为 HTTP/2 多路复用代理。

标注

想要强调部分内容，可以将它们设置为警告，提示，建议或引用。所有标注都使用了非常相似的 Shortcode：

  1. {{< warning >}}
  2. 这是一个重要的警告
  3. {{< /warning >}}
  5. {{< idea >}}
  6. 这是一个好点子
  7. {{< /idea >}}
  9. {{< tip >}}
  10. 这是来自专家的有用建议
  11. {{< /tip >}}
  13. {{< quote >}}
  14. 这是从某处引用的内容
  15. {{< /quote >}}

上面的 Shortcode 渲染结果如下：

这是一个重要的警告

这是一个好点子

这是来自专家的有用建议

这是从某处引用的内容

应该谨慎地使用标注。每种类型的标注都有特定的用途，过度使用会适得其反。通常，每个文件最多只能包含一个标注。

使用样板文本

要想在保持内容单一来源的情况下重用内容，请使用样板 Shortcode。要将样板文本嵌入任何内容文件中， 请如下使用 boilerplate 这种 Shortcode：

  1. {{< boilerplate example >}}

下面的 Shortcode 包含了 /content/zh/boilerplates/ 目录下 example.md 文件的内容：

这是一些 markdown 文本的样板。

  1. 嵌套文本块样本的例子。

该示例表明，您需要在想要插入样本内容的位置，填写 Markdown 文件的文件名。 您可以在 /content/zh/boilerplates 目录中找到现有的全部样板文件。

使用选项卡

要显示具有多个选项或格式的内容，请使用选项卡和选项卡集。其可用于显示：

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

要添加选项卡式内容，请组合使用 Shortcode 标识符 tabset 和 tabs，例如：

  1. {{< tabset category-name="platform" >}}
  3. {{< tab name="One" category-value="one" >}}
  4. ONE
  5. {{< /tab >}}
  7. {{< tab name="Two" category-value="two" >}}
  8. TWO
  9. {{< /tab >}}
  11. {{< tab name="Three" category-value="three" >}}
  12. THREE
  13. {{< /tab >}}
  15. {{< /tabset >}}

上面的 Shortcode，渲染效果如下：

ONE

TWO

THREE

每个选项卡的 name 属性的值就是该选项卡显示的文本。在每个选项卡内部，支持绝大部分的 Markdown 语法， 但是选项卡有一些限制。

category-name 和 category-value 属性是可选的，它们让选定的标签可以跨页面存储。 例如，访问者选择一个选项卡，并使用给定的名称和值自动保存他们的选择。如果有多个选项卡集使用了相同的 category-name 和 category-value，则它们的选择将自动跨页面同步。 当站点中有许多具有相同类型格式的选项卡集时，此功能特别有用。

例如，有多个选项卡集都提供了 GCP、BlueMix 和 AWS 三个选项。您可以将 category-name 属性的值设置为 environment，将 category-value 属性的值设置为 gcp，接着是 bluemix 和 aws。然后，当读者在某一个选项卡集中做出选择时，网站上所有相同的选项卡集都会自动做出相同的选择。

选项卡限制

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

  • 标题。选项卡中的标题会出现在目录中，但是单击目录中的链接不会自动跳到选项卡的位置。

  • 嵌套选项卡集。不要嵌套选项卡集。这么做会导致阅读体验很糟糕，并可能导致严重的混乱。

使用横幅和标签

要通告即将发生的事件或发布新消息，您可以按顺序自动地将对时间敏感的横幅和标签（banner 和 sticker）添加至生成的网站。我们为通告实现了以下 Shortcode：

  • 倒计时标签：它会显示现在距离事件发生还有多少时间，例如： “距 3 月 30 日 ServiceMeshCon 还剩 37 天”。标签在活动开始前会对读者产生视觉影响，应谨慎使用。

  • 横幅：它们向读者展示即将、正在或已经发生的重大事件的重要信息。例如： “Istio 1.5 已发布，请立即下载！”或“3 月 30 日加入我们的 ServiceMeshCon”。 横幅是活动期间向读者显示的全屏切片。

要创建横幅和标签，您可以在 events/banners 或 events/stickers 目录中创建 Markdown 文件。每个事件一个 Markdown 文件，并使用专用的 front-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 让链接指向当前最新版本的公告页面。