使用短代碼

閱讀時間 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。當您參考網路上的檔案時，請使用 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 的 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 檔案，並使用專用的 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` 來引入指向目前版本發布公告頁面的連結。