自定義 Hugo Shortcodes

本文件解釋了可在 Kubernetes Markdown 文件中使用的自定義 Hugo 簡碼。

在 Hugo 文件 中閱讀有關簡碼的更多資訊。

功能狀態

在本站的 Markdown 頁面（.md 檔案）中，您可以新增一個簡碼來顯示文件中功能的版本和狀態。

功能狀態演示

下面是功能狀態片段的演示，它顯示該功能在最新 Kubernetes 版本中是穩定的。

{{< feature-state state="stable" >}}

渲染效果

state 的有效值為

• alpha
• beta
• deprecated
• stable

功能狀態程式碼

顯示的 Kubernetes 版本預設為頁面或站點的版本。您可以透過傳遞 for_k8s_version 簡碼引數來更改功能狀態版本。例如：

{{< feature-state for_k8s_version="v1.10" state="beta" >}}

渲染效果

從描述檔案檢索功能狀態

為了動態確定功能的狀​​態，請使用 feature_gate_name 簡碼引數。功能狀態詳細資訊將從位於 content/en/docs/reference/command-line-tools-reference/feature-gates/ 的相應功能門描述檔案中提取。例如：

{{< feature-state feature_gate_name="NodeSwap" >}}

渲染效果

功能門描述

在本站的 Markdown 頁面（.md 檔案）中，您可以新增一個簡碼來顯示簡碼的描述。

功能門描述演示

下面是功能狀態片段的演示，它顯示該功能在最新 Kubernetes 版本中是穩定的。

{{< feature-gate-description name="DryRun" >}}

渲染效果

DryRun：啟用伺服器端 dry run 請求，以便在不提交的情況下測試驗證、合併和更改。

詞彙表

有兩種術語表簡碼：glossary_tooltip 和 glossary_definition。

您可以透過包含自動更新並用相關連結替換 我們的術語表 內容的方式來引用術語表術語。當滑鼠懸停在術語表術語上時，術語表條目將顯示一個工具提示。術語表術語也顯示為連結。

除了包含工具提示的內容外，您還可以在頁面內容中重用術語表中的定義。

術語表術語的原始資料儲存在 術語表目錄 中，每個術語表術語都有一個內容檔案。

術語表示例

例如，Markdown 中的以下包含將渲染為帶工具提示的 叢集

{{< glossary_tooltip text="cluster" term_id="cluster" >}}

這是一個簡短的術語表定義

{{< glossary_definition prepend="A cluster is" term_id="cluster" length="short" >}}

其渲染效果如下

叢集是一組稱為 節點 的 worker 機器，用於執行容器化應用程式。每個叢集至少有一個 worker 節點。

您也可以包含完整的定義

{{< glossary_definition term_id="cluster" length="all" >}}

其渲染效果如下

一組稱為 節點 的 worker 機器，用於執行容器化應用程式。每個叢集至少有一個 worker 節點。

worker 節點（或節點）承載應用程式工作負載的元件 Pod。控制平面 管理 worker 節點和叢集中的 Pod。在生產環境中，控制平面通常執行在多臺計算機上，而叢集通常執行多個節點，提供容錯和高可用性。

連結到 API 參考

您可以使用 api-reference 簡碼連結到 Kubernetes API 參考頁面，例如連結到 Pod 參考

{{< api-reference page="workload-resources/pod-v1" >}}

page 引數的內容是 API 參考頁 URL 的字尾。

您可以透過指定 anchor 引數連結到頁面中的特定位置，例如連結到 PodSpec 參考或頁面中的 環境變數 部分

{{< api-reference page="workload-resources/pod-v1" anchor="PodSpec" >}}
{{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" >}}

您可以透過指定 text 引數來更改連結的文字，例如，透過連結到頁面的 環境變數 部分

{{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" text="Environment Variable" >}}

表格標題

透過新增表格標題，可以使表格對螢幕閱讀器更加友好。要為表格新增 caption，請將表格用 table 簡碼括起來，並使用 caption 引數指定標題。

這是一個例子

{{< table caption="Configuration parameters" >}}
Parameter | Description | Default
:---------|:------------|:-------
`timeout` | The timeout for requests | `30s`
`logLevel` | The log level for log output | `INFO`
{{< /table >}}

渲染後的表格如下所示

如果您檢查表格的 HTML，您應該會在開啟的 <table> 元素之後立即看到這個元素

<caption style="display: none;">Configuration parameters</caption>

標籤頁

在本站的 Markdown 頁面（.md 檔案）中，您可以新增一個標籤頁集來顯示給定解決方案的多種形式。

tabs 簡碼接受以下引數：

• name：顯示在標籤頁上的名稱。
• codelang：如果您為 tab 簡碼提供內部內容，您可以告訴 Hugo 使用哪種程式語言進行高亮顯示。
• include：要在標籤頁中包含的檔案。如果標籤頁位於 Hugo 的 leaf bundle 中，則該檔案（可以是 Hugo 支援的任何 MIME 型別）將在 bundle 本身中查詢。如果不是，則要包含的內容頁面將在當前頁面相對查詢。請注意，使用 include 時，您沒有簡碼的內部內容，並且必須使用自閉合語法。例如，{{< tab name="Content File #1" include="example1" />}}。語言需要在 codelang 下指定，或者根據檔名確定語言。非內容檔案預設會進行程式碼高亮。
• 如果您的內部內容是 Markdown，您必須使用 % 分隔符來包圍標籤頁。例如，{{% tab name="Tab 1" %}}This is **markdown**{{% /tab %}}
• 您可以在標籤頁集中組合上述變體。

下面是標籤頁簡碼的演示。

標籤頁演示：程式碼高亮

{{< tabs name="tab_with_code" >}}
{{< tab name="Tab 1" codelang="bash" >}}
echo "This is tab 1."
{{< /tab >}}
{{< tab name="Tab 2" codelang="go" >}}
println "This is tab 2."
{{< /tab >}}
{{< /tabs >}}

渲染效果

• 標籤頁 1
• 標籤頁 2

echo "This is tab 1."

println "This is tab 2."

標籤頁演示：行內 Markdown 和 HTML

{{< tabs name="tab_with_md" >}}
{{% tab name="Markdown" %}}
This is **some markdown.**
{{< note >}}
It can even contain shortcodes.
{{< /note >}}
{{% /tab %}}
{{< tab name="HTML" >}}
<div>
	<h3>Plain HTML</h3>
	<p>This is some <i>plain</i> HTML.</p>
</div>
{{< /tab >}}
{{< /tabs >}}

渲染效果

• Markdown
• HTML

標籤頁演示：檔案包含

{{< tabs name="tab_with_file_include" >}}
{{< tab name="Content File #1" include="example1" />}}
{{< tab name="Content File #2" include="example2" />}}
{{< tab name="JSON File" include="podtemplate" />}}
{{< /tabs >}}

渲染效果

• 內容檔案 #1
• 內容檔案 #2
• JSON 檔案

  {
    "apiVersion": "v1",
    "kind": "PodTemplate",
    "metadata": {
      "name": "nginx"
    },
    "template": {
      "metadata": {
        "labels": {
          "name": "nginx"
        },
        "generateName": "nginx-"
      },
      "spec": {
         "containers": [{
           "name": "nginx",
           "image": "dockerfile/nginx",
           "ports": [{"containerPort": 80}]
         }]
      }
    }
  }

原始碼檔案

您可以使用 {{% code_sample %}} 簡碼將檔案的內容嵌入程式碼塊中，以便使用者下載或將其內容複製到剪貼簿。當示例檔案的內容是通用且可重用，並且您希望使用者自己嘗試時，可以使用此簡碼。

此簡碼接受兩個命名引數：language 和 file。必需引數 file 用於指定要顯示的檔案路徑。可選引數 language 用於指定檔案的程式語言。如果未提供 language 引數，簡碼將嘗試根據副檔名猜測語言。

例如

{{% code_sample language="yaml" file="application/deployment-scale.yaml" %}}

輸出為：

application/deployment-scale.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  replicas: 4 # Update the replicas from 2 to 4
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.16.1
        ports:
        - containerPort: 80

新增新示例檔案（例如 YAML 檔案）時，請將檔案建立在 <LANG>/examples/ 子目錄之一中，其中 <LANG> 是頁面的語言。在頁面的 Markdown 中，使用 code 簡碼

{{% code_sample file="<RELATIVE-PATH>/example-yaml>" %}}

其中 <RELATIVE-PATH> 是要包含的示例檔案相對於 examples 目錄的路徑。以下簡碼引用了位於 /content/en/examples/configmap/configmaps.yaml 的 YAML 檔案。

{{% code_sample file="configmap/configmaps.yaml" %}}

舊的 {{% codenew %}} 簡碼正在被 {{% code_sample %}} 取代。在新文件中請使用 {{% code_sample %}}（而不是 {{% codenew %}} 或 {{% code %}}）。

第三方內容標記

執行 Kubernetes 需要第三方軟體。例如：通常需要為您的叢集新增 DNS 伺服器，以便名稱解析正常工作。

當我們連結到第三方軟體或提及它時，我們會遵循 內容指南，並且還會標記這些第三方專案。

使用這些簡碼會在任何使用它們的文件頁面上新增免責宣告。

列表

要獲取多個第三方專案列表，請新增

{{% thirdparty-content %}}

緊跟包含所有專案的節的標題下方。

專案

如果您有一個列表，其中大多數專案都指向專案內部軟體（例如：Kubernetes 本身，以及獨立的 Descheduler 元件），那麼有另一種形式可以使用。

新增簡碼

{{% thirdparty-content single="true" %}}

在專案之前，或者緊跟特定專案標題的下方。

詳情

您可以使用簡碼渲染 <details> HTML 元素

{{< details summary="More about widgets" >}}
The frobnicator extension API implements _widgets_ using example running text.

Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur,
adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et
dolore magnam aliquam quaerat voluptatem.
{{< /details >}}

這渲染為

版本字串

要生成用於包含在文件中的版本字串，您可以從幾個版本簡碼中選擇。每個版本簡碼都顯示一個版本字串，該字串源自站點配置檔案 hugo.toml 中找到的版本引數的值。兩個最常用的版本引數是 latest 和 version。

{{< param "version" >}}

{{< param "version" >}} 簡碼從 version 站點引數生成當前 Kubernetes 文件版本的​​值。param 簡碼接受一個站點引數的名稱，在本例中為：version。

渲染效果

{{< latest-version >}}

{{< latest-version >}} 簡碼返回 latest 站點引數的值。latest 站點引數在新文件版本釋出時更新。此引數並不總是與文件集中的 version 值匹配。

渲染效果

{{< latest-semver >}}

{{< latest-semver >}} 簡碼生成 latest 的值，不帶 "v" 字首。

渲染效果

{{< version-check >}}

{{< version-check >}} 簡碼檢查 min-kubernetes-server-version 頁面引數是否存在，然後使用此值與 version 進行比較。

渲染效果

要檢查版本，請輸入 kubectl version。

{{< latest-release-notes >}}

{{< latest-release-notes >}} 簡碼從 latest 生成版本字串並刪除 "v" 字首。簡碼列印一個新 URL 到釋出說明 CHANGELOG 頁面，其中包含修改後的版本字串。

渲染效果

下一步

• 瞭解 Hugo。
• 瞭解 如何撰寫新主題。
• 瞭解 頁面內容型別。
• 瞭解 如何提交拉取請求。
• 瞭解 高階貢獻。