mirror of https://github.com/istio/istio.io.git
[zh] improve shortcodes (#14219)
Signed-off-by: xin.li <xin.li@daocloud.io>
This commit is contained in:
my-git9
GitHub
parent
886b0f6d41
commit
1d24319d3d
|
|
@ -10,13 +10,15 @@ aliases:
|
|||
keywords: [contribute]
|
||||
---
|
||||
|
||||
Hugo 的 Shortcode 是具有特定语法的特殊占位符，您可以将其添加到内容中以创建动态内容体验，例如选项卡、图片、图标、指向另一个页面的链接以及特殊内容布局。
|
||||
Hugo 的 Shortcode 是具有特定语法的特殊占位符，您可以将其添加到内容中以创建动态内容体验，
|
||||
例如选项卡、图片、图标、指向另一个页面的链接以及特殊内容布局。
|
||||
|
||||
本页面介绍了可用的 Shortcode 及其用法。
|
||||
|
||||
## 添加图片{#add-images}
|
||||
## 添加图片 {#add-images}
|
||||
|
||||
将图片文件跟 Markdown 文件放在相同的目录。为了增强其可读性，以及方便本地化，首选的图片格式是 SVG。下面的示例展示了添加带有图片的 Shortcode，所需的必填字段：
|
||||
将图片文件跟 Markdown 文件放在相同的目录。为了增强其可读性，以及方便本地化，
|
||||
首选的图片格式是 SVG。下面的示例展示了添加带有图片的 Shortcode，所需的必填字段：
|
||||
|
||||
{{< text html >}}
|
||||
{{</* image width="75%" ratio="45.34%"
|
||||
|
|
@ -36,13 +38,15 @@ Hugo 的 Shortcode 是具有特定语法的特殊占位符，您可以将其添
|
|||
*/>}}
|
||||
{{< /text >}}
|
||||
|
||||
如果您没有填写 `alt` 字段，Hugo 会自动使用 `title` 的文本。如果您没有填写 `title` 字段，Hugo 会自动使用 `caption` 的文本。
|
||||
如果您没有填写 `alt` 字段，Hugo 会自动使用 `title` 的文本。如果您没有填写 `title` 字段，
|
||||
Hugo 会自动使用 `caption` 的文本。
|
||||
|
||||
`width` 字段设置图像相对于周围文本的大小，默认为 100％。
|
||||
|
||||
`Ratio` 字段设置图像相对于其宽度的高度。Hugo 会自动为目录中的图片计算该值。但是，对于外部图片，您必须手动为其计算。将 `ratio` 的值设置为 `([图片高度]/[图片宽度]) * 100`。
|
||||
`Ratio` 字段设置图像相对于其宽度的高度。Hugo 会自动为目录中的图片计算该值。但是，
|
||||
对于外部图片，您必须手动为其计算。将 `ratio` 的值设置为 `([图片高度]/[图片宽度]) * 100`。
|
||||
|
||||
## 添加图标{#add-icons}
|
||||
## 添加图标 {#add-icons}
|
||||
|
||||
您可以将通用图标嵌入到具有以下内容的内容中：
|
||||
|
||||
|
|
@ -54,25 +58,29 @@ Hugo 的 Shortcode 是具有特定语法的特殊占位符，您可以将其添
|
|||
{{</* tip_icon */>}}
|
||||
{{< /text >}}
|
||||
|
||||
图标会呈现在文本中，例如：{{< warning_icon >}}、{{< idea_icon >}}、{{< checkmark_icon >}}、{{< cancel_icon >}} 以及 {{< tip_icon >}}。
|
||||
图标会呈现在文本中，例如：{{< warning_icon >}}、{{< idea_icon >}}、
|
||||
{{< checkmark_icon >}}、{{< cancel_icon >}} 以及 {{< tip_icon >}}。
|
||||
|
||||
## 添加指向其它页面的链接{#add-links-to-other-pages}
|
||||
## 添加指向其它页面的链接 {#add-links-to-other-pages}
|
||||
|
||||
根据目标的不同，Istio 文档支持三种类型的链接。每种类型使用不同的语法来表示链接目标。
|
||||
|
||||
- **外部链接**。用于指向 Istio 在 GitHub 的仓库，或者其它的站外链接。使用标准的 Markdown 语法表示 URL。当您引用的文件在互联网上时，请尽量使用 HTTPS 协议，例如：
|
||||
- **外部链接**：用于指向 Istio 在 GitHub 的仓库，或者其它的站外链接。使用标准的
|
||||
Markdown 语法表示 URL。当您引用的文件在互联网上时，请尽量使用 HTTPS 协议，例如：
|
||||
|
||||
{{< text markdown >}}
|
||||
[链接的描述文本](https://mysite/myfile.html)
|
||||
{{< /text >}}
|
||||
|
||||
- **相对链接**。用于指向与当前文件位于同一级，或者更深层级的目标。相对链接以点 `.` 开头，例如：
|
||||
- **相对链接**：用于指向与当前文件位于同一级，或者更深层级的目标。相对链接以点
|
||||
`.` 开头，例如：
|
||||
|
||||
{{< text markdown >}}
|
||||
[链接到同级或子页面](./sub-dir/child-page.html)
|
||||
{{< /text >}}
|
||||
|
||||
- **绝对链接**。用于指向当前页面之外，但位于 Istio 站点之内页面的目标。绝对路径以斜线 `/` 开头，例如：
|
||||
- **绝对链接**：用于指向当前页面之外，但位于 Istio 站点之内页面的目标。
|
||||
绝对路径以斜线 `/` 开头，例如：
|
||||
|
||||
{{< text markdown >}}
|
||||
[链接到关于页面](/zh/about/)
|
||||
|
|
@ -80,40 +88,47 @@ Hugo 的 Shortcode 是具有特定语法的特殊占位符，您可以将其添
|
|||
|
||||
无论使用何种类型，链接都不会指向内容的 `index.md` 文件，而是指向包含 `index.md` 的那个目录。
|
||||
|
||||
### 添加指向 GitHub 内容的链接{#add-links-to-content-on-GitHub}
|
||||
### 添加指向 GitHub 内容的链接 {#add-links-to-content-on-GitHub}
|
||||
|
||||
有几种方法可以引用 GitHub 的内容或文件：
|
||||
|
||||
- **{{</* github_file */>}}**，用于引用 GitHub 中的单个文件（例如 yaml 文件）。该 shortcode 会渲染为 `https://raw.githubusercontent.com/istio/istio*`，例如：
|
||||
- **{{</* github_file */>}}**，用于引用 GitHub 中的单个文件（例如 yaml 文件）。
|
||||
该 Shortcode 会渲染为 `https://raw.githubusercontent.com/istio/istio*`，例如：
|
||||
|
||||
{{< text markdown >}}
|
||||
[liveness]({{</* github_file */>}}/samples/health-check/liveness-command.yaml)
|
||||
{{< /text >}}
|
||||
|
||||
- **{{</* github_tree */>}}**，用于引用 GitHub 中的一个目录。该 shortcode 会渲染为 `https://github.com/istio/istio/tree*`，例如：
|
||||
- **{{</* github_tree */>}}**，用于引用 GitHub 中的一个目录。该 Shortcode
|
||||
会渲染为 `https://github.com/istio/istio/tree*`，例如：
|
||||
|
||||
{{< text markdown >}}
|
||||
[httpbin]({{</* github_tree */>}}/samples/httpbin)
|
||||
{{< /text >}}
|
||||
|
||||
- **{{</* github_blob */>}}**，用于引用 GitHub 中的单个文件，该 shortcode 会渲染为 `https://github.com/istio/istio/blob*`，例如：
|
||||
- **{{</* github_blob */>}}**，用于引用 GitHub 中的单个文件，该 Shortcode 会渲染为
|
||||
`https://github.com/istio/istio/blob*`，例如：
|
||||
|
||||
{{< text markdown >}}
|
||||
[RawVM MySQL]({{</* github_blob */>}}/samples/rawvm/README.md)
|
||||
{{< /text >}}
|
||||
|
||||
上面的 shortcode 会根据文档当前的目标分支，生成指向 GitHub 中对应分支的链接。要查看当前目标分支的名称，可以使用 `{{</* source_branch_name */>}}` shortcode 来获取当前目标分支的名称。
|
||||
上面的 Shortcode 会根据文档当前的目标分支，生成指向 GitHub 中对应分支的链接。
|
||||
要查看当前目标分支的名称，可以使用 `{{</* source_branch_name */>}}` Shortcode
|
||||
来获取当前目标分支的名称。
|
||||
|
||||
## 版本信息{#version-information}
|
||||
## 版本信息 {#version-information}
|
||||
|
||||
想要通过从网站检索，在您的内容中显示 Istio 的当前版本，请使用以下这些 Shortcode：
|
||||
|
||||
- `{{</* istio_version */>}}`，渲染结果为：{{< istio_version >}}
|
||||
- `{{</* istio_full_version */>}}`，渲染结构为：{{< istio_full_version >}}
|
||||
|
||||
## 术语表{#glossary-terms}
|
||||
## 术语表 {#glossary-terms}
|
||||
|
||||
当在某个页面中提及一个 Istio 术语时，贡献补充条款要求您将该术语包含在 `glossary` 中，并在本页第一次出现这个术语时使用 Shortcode `{{</* gloss */>}}` 进行标记。这种 Shortcode 会生成一个特殊的渲染效果，读者点击该术语，可以在弹出的窗口中获取该术语的定义。例如：
|
||||
当在某个页面中提及一个 Istio 术语时，贡献补充条款要求您将该术语包含在 `glossary` 中，
|
||||
并在本页第一次出现这个术语时使用 Shortcode `{{</* gloss */>}}` 进行标记。这种
|
||||
Shortcode 会生成一个特殊的渲染效果，读者点击该术语，可以在弹出的窗口中获取该术语的定义。例如：
|
||||
|
||||
{{< text markdown >}}
|
||||
Istio 里的组件通过控制 {{<gloss>}}Envoy{{</gloss>}} 代理，实现服务发现、负载均衡和路由分发。
|
||||
|
|
@ -123,7 +138,8 @@ Istio 里的组件通过控制 {{<gloss>}}Envoy{{</gloss>}} 代理，实现服
|
|||
|
||||
Istio 里的组件通过控制 {{< gloss >}}Envoy{{< /gloss >}} 代理，实现服务发现、负载均衡和路由分发。
|
||||
|
||||
如果您想在您的文本中使用该术语的其它形式，您依然可以使用该 shortcode。要修改显示文本，只需在 shortcode 中包含对应的术语条目即可。例如：
|
||||
如果您想在您的文本中使用该术语的其它形式，您依然可以使用该 Shortcode。
|
||||
要修改显示文本，只需在 Shortcode 中包含对应的术语条目即可。例如：
|
||||
|
||||
{{< text markdown >}}
|
||||
{{</*gloss envoy*/>}}Envoy{{</*/gloss*/>}} 的 HTTP 支持首先被设计为 HTTP/2 多路复用代理。
|
||||
|
|
@ -133,7 +149,7 @@ Istio 里的组件通过控制 {{< gloss >}}Envoy{{< /gloss >}} 代理，实现
|
|||
|
||||
{{< gloss envoy >}}Envoy{{</ gloss >}} 的 HTTP 支持首先被设计为 HTTP/2 多路复用代理。
|
||||
|
||||
## 标注{#callouts}
|
||||
## 标注 {#callouts}
|
||||
|
||||
想要强调部分内容，可以将它们设置为警告，提示，建议或引用。所有标注都使用了非常相似的 Shortcode：
|
||||
|
||||
|
|
@ -155,7 +171,7 @@ Istio 里的组件通过控制 {{< gloss >}}Envoy{{< /gloss >}} 代理，实现
|
|||
{{</* /quote */>}}
|
||||
{{< /text >}}
|
||||
|
||||
上面的 shortcode 渲染结果如下：
|
||||
上面的 Shortcode 渲染结果如下：
|
||||
|
||||
{{< warning >}}
|
||||
这是一个重要的警告
|
||||
|
|
@ -175,21 +191,23 @@ Istio 里的组件通过控制 {{< gloss >}}Envoy{{< /gloss >}} 代理，实现
|
|||
|
||||
应该谨慎地使用标注。每种类型的标注都有特定的用途，过度使用会适得其反。通常，每个文件最多只能包含一个标注。
|
||||
|
||||
## 使用样板文本{#use-boilerplate-text}
|
||||
## 使用样板文本 {#use-boilerplate-text}
|
||||
|
||||
要想在保持内容单一来源的情况下重用内容，请使用样板 shortcode。要将样板文本嵌入任何内容文件中，请如下使用 `boilerplate` 这种 Shortcode：
|
||||
要想在保持内容单一来源的情况下重用内容，请使用样板 Shortcode。要将样板文本嵌入任何内容文件中，
|
||||
请如下使用 `boilerplate` 这种 Shortcode：
|
||||
|
||||
{{< text markdown >}}
|
||||
{{</* boilerplate example */>}}
|
||||
{{< /text >}}
|
||||
|
||||
下面的 shortcode 包含了 `/content/zh/boilerplates/` 目录下 `example.md` 文件的内容：
|
||||
下面的 Shortcode 包含了 `/content/zh/boilerplates/` 目录下 `example.md` 文件的内容：
|
||||
|
||||
{{< boilerplate example >}}
|
||||
|
||||
该示例表明，您需要在想要插入样本内容的位置，填写 Markdown 文件的文件名。您可以在 `/content/zh/boilerplates` 目录中找到现有的全部样板文件。
|
||||
该示例表明，您需要在想要插入样本内容的位置，填写 Markdown 文件的文件名。
|
||||
您可以在 `/content/zh/boilerplates` 目录中找到现有的全部样板文件。
|
||||
|
||||
## 使用选项卡{#use-tabs}
|
||||
## 使用选项卡 {#use-tabs}
|
||||
|
||||
要显示具有多个选项或格式的内容，请使用选项卡和选项卡集。其可用于显示：
|
||||
|
||||
|
|
@ -217,7 +235,7 @@ THREE
|
|||
{{</* /tabset */>}}
|
||||
{{< /text >}}
|
||||
|
||||
上面的 shortcode，渲染效果如下：
|
||||
上面的 Shortcode，渲染效果如下：
|
||||
|
||||
{{< tabset category-name="platform" >}}
|
||||
|
||||
|
|
@ -235,29 +253,40 @@ THREE
|
|||
|
||||
{{< /tabset >}}
|
||||
|
||||
每个选项卡的 `name` 属性的值就是该选项卡显示的文本。在每个选项卡内部，支持绝大部分的 Markdown 语法，但是选项卡有一些[限制](#tab-limitations)。
|
||||
每个选项卡的 `name` 属性的值就是该选项卡显示的文本。在每个选项卡内部，支持绝大部分的 Markdown 语法，
|
||||
但是选项卡有一些[限制](#tab-limitations)。
|
||||
|
||||
`category-name` 和 `category-value` 属性是可选的，它们让选定的标签可以跨页面存储。例如，访问者选择一个选项卡，并使用给定的名称和值自动保存他们的选择。如果有多个选项卡集使用了相同的 `category-name` 和 `category-value`，则它们的选择将自动跨页面同步。当站点中有许多具有相同类型格式的选项卡集时，此功能特别有用。
|
||||
`category-name` 和 `category-value` 属性是可选的，它们让选定的标签可以跨页面存储。
|
||||
例如，访问者选择一个选项卡，并使用给定的名称和值自动保存他们的选择。如果有多个选项卡集使用了相同的
|
||||
`category-name` 和 `category-value`，则它们的选择将自动跨页面同步。
|
||||
当站点中有许多具有相同类型格式的选项卡集时，此功能特别有用。
|
||||
|
||||
例如，有多个选项卡集都提供了 `GCP`、`BlueMix` 和 `AWS` 三个选项。您可以将 `category-name` 属性的值设置为 `environment`，将 `category-value` 属性的值设置为`gcp`，接着是 `bluemix` 和 `aws`。然后，当读者在某一个选项卡集中做出选择时，网站上所有相同的选项卡集都会自动做出相同的选择。
|
||||
例如，有多个选项卡集都提供了 `GCP`、`BlueMix` 和 `AWS` 三个选项。您可以将 `category-name`
|
||||
属性的值设置为 `environment`，将 `category-value` 属性的值设置为 `gcp`，接着是
|
||||
`bluemix` 和 `aws`。然后，当读者在某一个选项卡集中做出选择时，网站上所有相同的选项卡集都会自动做出相同的选择。
|
||||
|
||||
### 选项卡限制{#tab-limitations}
|
||||
### 选项卡限制 {#tab-limitations}
|
||||
|
||||
您可以在选项卡中使用几乎所有的 Markdown 语法，但以下情况除外：
|
||||
|
||||
- *标题*。选项卡中的标题会出现在目录中，但是单击目录中的链接不会自动跳到选项卡的位置。
|
||||
- **标题**。选项卡中的标题会出现在目录中，但是单击目录中的链接不会自动跳到选项卡的位置。
|
||||
|
||||
- *嵌套选项卡集*。不要嵌套选项卡集。这么做会导致阅读体验很糟糕，并可能导致严重的混乱。
|
||||
- **嵌套选项卡集**。不要嵌套选项卡集。这么做会导致阅读体验很糟糕，并可能导致严重的混乱。
|
||||
|
||||
## 使用横幅和标签{#use-banners-and-stickers}
|
||||
## 使用横幅和标签 {#use-banners-and-stickers}
|
||||
|
||||
要通告即将发生的事件或发布新消息，您可以按顺序自动地将对时间敏感的横幅和标签（banner 和 sticker）添加至生成的网站。我们为通告实现了以下 Shortcode：
|
||||
要通告即将发生的事件或发布新消息，您可以按顺序自动地将对时间敏感的横幅和标签（banner
|
||||
和 sticker）添加至生成的网站。我们为通告实现了以下 Shortcode：
|
||||
|
||||
- **倒计时标签**：它会显示现在距离事件发生还有多少时间，例如：“距 3 月 30 日 ServiceMeshCon 还剩 37 天”。标签在活动开始前会对读者产生视觉影响，应谨慎使用。
|
||||
- **倒计时标签**：它会显示现在距离事件发生还有多少时间，例如：
|
||||
“距 3 月 30 日 ServiceMeshCon 还剩 37 天”。标签在活动开始前会对读者产生视觉影响，应谨慎使用。
|
||||
|
||||
- **横幅**：它们向读者展示即将、正在或已经发生的重大事件的重要信息。例如，“Istio 1.5 已发布，请立即下载！”或“3 月 30 日加入我们的 ServiceMeshCon”。横幅是活动期间向读者显示的全屏切片。
|
||||
- **横幅**：它们向读者展示即将、正在或已经发生的重大事件的重要信息。例如：
|
||||
“Istio 1.5 已发布，请立即下载！”或“3 月 30 日加入我们的 ServiceMeshCon”。
|
||||
横幅是活动期间向读者显示的全屏切片。
|
||||
|
||||
要创建横幅和标签，您可以在 `events/banners` 或 `events/stickers` 目录中创建 Markdown 文件。每个事件一个 Markdown 文件，并使用专用的 front-matter 字段来控制其行为。下表列举了可用的字段：
|
||||
要创建横幅和标签，您可以在 `events/banners` 或 `events/stickers` 目录中创建 Markdown
|
||||
文件。每个事件一个 Markdown 文件，并使用专用的 front-matter 字段来控制其行为。下表列举了可用的字段：
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
|
|
|
|||
Loading…
Reference in New Issue