程式碼區塊的渲染 Hook

Markdown

以下的 Markdown 範例包含一個圍欄程式碼區塊：

```bash {class="my-class" id="my-codeblock" lineNos=inline tabWidth=2}
declare a=1
echo "$a"
exit
```

一個圍欄程式碼區塊由以下部分組成：

• 一個開頭的 程式碼圍欄
• 一個選填的 資訊字串
• 一段程式碼範例
• 一個結尾的程式碼圍欄

在上述範例中，資訊字串包含：

• 程式碼範例的語言（第一個單詞）
• 一個選填的以空格或逗號分隔的屬性列表（大括號中的內容）

資訊字串中的屬性可以是通用屬性或高亮選項。

在上述範例中，通用屬性是 class 和 id。如果程式碼區塊渲染 Hook 中沒有特別處理，Hugo 會將每個通用屬性添加到包裹渲染後程式碼區塊的 HTML 元素中。基於其內容安全模型，Hugo 會移除 HTML 事件屬性，例如 onclick 和 onmouseover。通用屬性通常是全域 HTML 屬性，但也可以包含自訂屬性。

在上述範例中，高亮選項為 lineNos 和 tabWidth。Hugo 使用 Chroma 語法高亮工具來渲染程式碼範例。您可以透過指定一個或多個 高亮選項 來控制渲染程式碼的外觀。

Context

程式碼區塊渲染 Hook 模板會接收到以下 上下文：

Attributes

(map) 來自資訊字串的通用屬性。

Inner

(string) 開頭與結尾程式碼圍欄之間的內容，不包括資訊字串。

Options

(map) 來自資訊字串的高亮選項。

Ordinal

(int) 頁面中程式碼區塊的零基索引。

Page

(page) 當前頁面的參考。

PageInner

(page) 通過 RenderShortcodes 方法嵌套的頁面參考。查看詳情。

Position

(text.Position) 程式碼區塊在頁面內容中的位置。

Type

(string) 資訊字串的第一個單詞，通常是程式碼語言。

範例

在預設設定下，Hugo 通過將程式碼範例傳遞給 Chroma 語法高亮工具並包裝結果來渲染圍欄程式碼區塊。以下是創建一個具備相同行為的渲染 Hook 的範例：

{{ $result := transform.HighlightCodeBlock . }}
{{ $result.Wrapped }}

雖然您可以使用帶有條件邏輯的一個模板來根據語言控制行為，但您也可以為每個語言創建特定的模板。

layouts/
└── _default/
    └── _markup/
        ├── render-codeblock-mermaid.html
        ├── render-codeblock-python.html
        └── render-codeblock.html

例如，要創建一個渲染 Mermaid 圖表的程式碼區塊渲染 Hook：

<pre class="mermaid">
  {{- .Inner | htmlEscape | safeHTML }}
</pre>
{{ .Page.Store.Set "hasMermaid" true }}

然後將此段程式碼加入基底模板的底部：

{{ if .Store.Get "hasMermaid" }}
  <script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs';
    mermaid.initialize({ startOnLoad: true });
  </script>
{{ end }}

詳細資訊請參考 圖表 頁面。

內嵌

Hugo 包含一個 內嵌程式碼區塊渲染 Hook，用於渲染 GoAT 圖表。

PageInner 詳細資訊

PageInner 的主要用途是解析相對於包含的 Page 的連結和 頁面資源。例如，建立一個「include」掛載程式碼，從多個內容檔案組合成一個頁面，同時保留註腳和目錄的全域上下文：

{{ with site.GetPage (.Get 0) }}
  {{ .RenderShortcodes }}
{{ end }}

然後在您的 Markdown 中呼叫此掛載程式碼：

{{% include "/posts/p2" %}}

在渲染 /posts/p2 時觸發的任何渲染掛載將獲得：

• /posts/p1 當呼叫 Page
• /posts/p2 當呼叫 PageInner

如果不相關，PageInner 將回退到 Page 的值，並始終返回一個值。

作為一個實際範例，Hugo 的內嵌連結和圖片渲染掛載使用 PageInner 方法解析 Markdown 中連結和圖片的目標位置。請參考以下來源程式碼：

• 內嵌連結渲染掛載
• 內嵌圖片渲染掛載