自訂 Hugo Shortcodes

此頁面說明可以在 Kubernetes Markdown 文件中使用的自訂 Hugo shortcode。

請在 Hugo 文件中閱讀有關 shortcode 的更多資訊。

功能狀態

在本網站的 Markdown 頁面 (.md 檔案) 中，您可以新增一個 shortcode 以顯示已記錄功能的版本和狀態。

功能狀態示範

以下是功能狀態程式碼片段的示範，它將功能顯示為最新 Kubernetes 版本中的穩定狀態。

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

呈現為

state 的有效值為

• alpha
• beta
• deprecated
• stable

功能狀態程式碼

顯示的 Kubernetes 版本預設為頁面或網站的版本。您可以透過傳遞 for_k8s_version shortcode 參數來變更功能狀態版本。例如

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

呈現為

從描述檔案中檢索功能狀態

若要動態判斷功能狀態，請使用 feature_gate_name shortcode 參數。功能狀態詳細資訊將從位於 content/en/docs/reference/command-line-tools-reference/feature-gates/ 中的對應功能閘道描述檔案中擷取。例如

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

呈現為

功能閘道描述

在本網站的 Markdown 頁面 (.md 檔案) 中，您可以新增一個 shortcode 以顯示 shortcode 的描述。

功能閘道描述示範

以下是功能狀態程式碼片段的示範，它將功能顯示為最新 Kubernetes 版本中的穩定狀態。

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

呈現為

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

詞彙表

有兩個詞彙表 shortcode：glossary_tooltip 和 glossary_definition。

您可以使用包含項來參考詞彙表術語，該包含項會自動更新並使用來自 我們的詞彙表的相關連結取代內容。當滑鼠停留在詞彙表術語上方時，詞彙表條目會顯示工具提示。詞彙表術語也會顯示為連結。

除了帶有工具提示的包含項之外，您還可以在頁面內容中重複使用詞彙表中的定義。

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

詞彙表示範

例如，Markdown 中的以下包含項呈現為 叢集，並帶有工具提示

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

這是一個簡短的詞彙表定義

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

呈現為

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

您也可以包含完整定義

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

呈現為

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

工作節點託管作為應用程式工作負載組件的 Pod。控制平面管理叢集中的工作節點和 Pod。在生產環境中，控制平面通常跨多部電腦執行，而叢集通常執行多個節點，以提供容錯能力和高可用性。

API 參考連結

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

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

page 參數的內容是 API 參考頁面 URL 的後綴。

您可以透過指定 anchor 參數來連結到頁面中的特定位置，例如連結到 PodSpec 參考或頁面的 environment-variables 區段

{{< 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" >}}

表格標題

您可以透過新增表格標題，讓螢幕閱讀器更容易存取表格。若要將 標題新增到表格，請使用 table shortcode 包圍表格，並使用 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 shortcode 接受以下參數

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

以下是 tabs shortcode 的示範。

分頁示範：程式碼語法突顯

{{< 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."

分頁示範：Inline 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 %}} shortcode 將檔案內容嵌入程式碼區塊中，讓使用者下載或複製其內容到剪貼簿。當範例檔案的內容是通用且可重複使用的，並且您希望使用者自行嘗試時，會使用此 shortcode。

此 shortcode 接受兩個具名參數：language 和 file。強制性參數 file 用於指定要顯示的檔案路徑。選用參數 language 用於指定檔案的程式語言。如果未提供 language 參數，shortcode 將嘗試根據檔案副檔名猜測語言。

例如

{{% 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 shortcode

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

其中 <RELATIVE-PATH> 是要包含的範例檔案的路徑，相對於 examples 目錄。以下 shortcode 參考位於 /content/en/examples/configmap/configmaps.yaml 的 YAML 檔案。

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

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

第三方內容標記

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

當我們連結到第三方軟體或以其他方式提及它時，我們會遵循內容指南，並且我們也會標記這些第三方項目。

使用這些 shortcode 會在任何使用它們的文件頁面中新增免責聲明。

清單

對於多個第三方項目的清單，請新增

{{% thirdparty-content %}}

在包含所有項目的章節標題下方。

項目

如果您的清單中大多數項目都指向專案內軟體（例如：Kubernetes 本身，以及獨立的 Descheduler 元件），則有不同的使用形式。

新增 shortcode

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

在項目之前，或在特定項目的標題下方。

詳細資訊

您可以使用 shortcode 呈現 <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 >}}

這會呈現為

版本字串

若要產生包含在文件中的版本字串，您可以從數個版本 shortcode 中選擇。每個版本 shortcode 都會顯示從網站設定檔 hugo.toml 中找到的版本參數值衍生的版本字串。兩個最常用的版本參數是 latest 和 version。

{{< param "version" >}}

{{< param "version" >}} shortcode 從 version 網站參數產生目前 Kubernetes 文件版本的數值。param shortcode 接受一個網站參數的名稱，在本例中為：version。

呈現為

{{< latest-version >}}

{{< latest-version >}} shortcode 傳回 latest 網站參數的值。當發布新版本的文件時，latest 網站參數會更新。此參數不一定與文件集中 version 的值相符。

呈現為

{{< latest-semver >}}

{{< latest-semver >}} shortcode 產生 latest 的值，但不包含 "v" 前綴。

呈現為

{{< version-check >}}

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

呈現為

{{< latest-release-notes >}}

{{< latest-release-notes >}} shortcode 從 latest 產生版本字串，並移除 "v" 前綴。此 shortcode 會印出新的發行說明 CHANGELOG 頁面的 URL，其中包含修改後的版本字串。

呈現為

下一步

• 瞭解 Hugo。
• 瞭解 撰寫新主題。
• 瞭解 頁面內容類型。
• 瞭解 開啟 Pull Request。
• 瞭解 進階貢獻。