Hugo 頁面資源

使用頁面資源將資產與頁面邏輯關聯。

頁面資源只能從 page bundles 訪問，這些目錄的根目錄有 index.md 或 _index.md 文件。頁面資源僅對與其 bundle 的頁面可用。

在此示例中，first-post 是一個頁面 bundle，可以訪問 10 個頁面資源，包括音頻、數據、文檔、圖像和視頻。雖然 second-post 也是頁面 bundle，但它沒有頁面資源，無法直接訪問與 first-post 關聯的頁面資源。

content
└── post
    ├── first-post
    │   ├── images
    │   │   ├── a.jpg
    │   │   ├── b.jpg
    │   │   └── c.jpg
    │   ├── index.md (頁面 bundle 的根)
    │   ├── latest.html
    │   ├── manual.json
    │   ├── notice.md
    │   ├── office.mp3
    │   ├── pocket.mp4
    │   ├── rating.pdf
    │   └── safety.txt
    └── second-post
        └── index.md (頁面 bundle 的根)

示例

在 Page 對象上使用以下任何方法來捕獲頁面資源：

一旦捕獲了資源，使用任何適用的 Resource 方法來返回值或執行操作。

以下示例假設此內容結構：

content/
└── example/
    ├── data/
    │  └── books.json   <-- 頁面資源
    ├── images/
    │  ├── a.jpg        <-- 頁面資源
    │  └── b.jpg        <-- 頁面資源
    ├── snippets/
    │  └── text.md      <-- 頁面資源
    └── index.md

渲染單個圖像，如果文件不存在則拋出錯誤：

{{ $path := "images/a.jpg" }}
{{ with .Resources.Get $path }}
  <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ else }}
  {{ errorf "Unable to get page resource %q" $path }}
{{ end }}

渲染所有圖像，調整大小為 300 像素寬：

{{ range .Resources.ByType "image" }}
  {{ with .Resize "300x" }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
  {{ end }}
{{ end }}

渲染 Markdown 片段：

{{ with .Resources.Get "snippets/text.md" }}
  {{ .Content }}
{{ end }}

列出數據文件中的標題，如果文件不存在則拋出錯誤。

{{ $path := "data/books.json" }}
{{ with .Resources.Get $path }}
  {{ with . | transform.Unmarshal }}
    <p>Books:</p>
    <ul>
      {{ range . }}
        <li>{{ .title }}</li>
      {{ end }}
    </ul>
  {{ end }}
{{ else }}
  {{ errorf "Unable to get page resource %q" $path }}
{{ end }}

元數據

頁面資源的元數據通過名為 resources 的數組/表參數從相應頁面的 front matter 管理。你可以使用通配符批量分配值。

page 類型的資源從其自己的 front matter 獲取 Title 等。

name: (string) 設置 Name 返回的值。

方法 Match、Get 和 GetMatch 使用 Name 來匹配資源。

title: (string) 設置 Title 返回的值
params: (map) 自定義鍵值對映射。

資源元數據示例

---
date: '2018-01-25'
resources:
- name: header
  src: images/sunset.jpg
- params:
    icon: photo
  src: documents/photo_specs.pdf
  title: Photo Specifications
- src: documents/guide.pdf
  title: Instruction Guide
- src: documents/checklist.pdf
  title: Document Checklist
- src: documents/payment.docx
  title: Proof of Payment
- name: pdf-file-:counter
  params:
    icon: pdf
  src: '**.pdf'
- params:
    icon: word
  src: '**.docx'
title: Application
---

+++
date = '2018-01-25'
title = 'Application'
[[resources]]
  name = 'header'
  src = 'images/sunset.jpg'
[[resources]]
  src = 'documents/photo_specs.pdf'
  title = 'Photo Specifications'
  [resources.params]
    icon = 'photo'
[[resources]]
  src = 'documents/guide.pdf'
  title = 'Instruction Guide'
[[resources]]
  src = 'documents/checklist.pdf'
  title = 'Document Checklist'
[[resources]]
  src = 'documents/payment.docx'
  title = 'Proof of Payment'
[[resources]]
  name = 'pdf-file-:counter'
  src = '**.pdf'
  [resources.params]
    icon = 'pdf'
[[resources]]
  src = '**.docx'
  [resources.params]
    icon = 'word'
+++

{
   "date": "2018-01-25",
   "resources": [
      {
         "name": "header",
         "src": "images/sunset.jpg"
      },
      {
         "params": {
            "icon": "photo"
         },
         "src": "documents/photo_specs.pdf",
         "title": "Photo Specifications"
      },
      {
         "src": "documents/guide.pdf",
         "title": "Instruction Guide"
      },
      {
         "src": "documents/checklist.pdf",
         "title": "Document Checklist"
      },
      {
         "src": "documents/payment.docx",
         "title": "Proof of Payment"
      },
      {
         "name": "pdf-file-:counter",
         "params": {
            "icon": "pdf"
         },
         "src": "**.pdf"
      },
      {
         "params": {
            "icon": "word"
         },
         "src": "**.docx"
      }
   ],
   "title": "Application"
}

從上面的示例：

sunset.jpg 將獲得新的 Name，現在可以使用 .GetMatch "header" 找到。
documents/photo_specs.pdf 將獲得 photo 圖標。
documents/checklist.pdf、documents/guide.pdf 和 documents/payment.docx 將獲得 title 設置的 Title。
bundle 中的每個 PDF（除了 documents/photo_specs.pdf）將獲得 pdf 圖標。
所有 PDF 文件將獲得新的 Name。name 參數包含特殊佔位符 :counter，因此 Name 將是 pdf-file-1、pdf-file-2、pdf-file-3。
bundle 中的每個 docx 將獲得 word 圖標。

順序很重要；只有 title、name 和 params 鍵的第一個設置值將被使用。連續參數將僅為尚未設置的參數設置。在上面的示例中，.Params.icon 首先在 src = "documents/photo_specs.pdf" 中設置為 "photo"。所以它不會被後面設置的 src = "**.pdf" 規則覆蓋為 "pdf"。

`name` 和 `title` 中的 `:counter` 佔位符

:counter 是 resources 的 name 和 title 參數中識別的特殊佔位符。

計數器在 name 或 title 中第一次使用時從 1 開始。

例如，如果 bundle 有資源 photo_specs.pdf、other_specs.pdf、guide.pdf 和 checklist.pdf，並且 front matter 已指定 resources 為：

---
resources:
- src: '*specs.pdf'
  title: 'Specification #:counter'
- name: pdf-file-:counter
  src: '**.pdf'
title: Engine inspections
---

+++
title = 'Engine inspections'
[[resources]]
  src = '*specs.pdf'
  title = 'Specification #:counter'
[[resources]]
  name = 'pdf-file-:counter'
  src = '**.pdf'
+++

{
   "resources": [
      {
         "src": "*specs.pdf",
         "title": "Specification #:counter"
      },
      {
         "name": "pdf-file-:counter",
         "src": "**.pdf"
      }
   ],
   "title": "Engine inspections"
}

Name 和 Title 將按如下方式分配給資源文件：

Resource file	`Name`	`Title`
checklist.pdf	`"pdf-file-1.pdf`	`"checklist.pdf"`
guide.pdf	`"pdf-file-2.pdf`	`"guide.pdf"`
other_specs.pdf	`"pdf-file-3.pdf`	`"Specification #1"`
photo_specs.pdf	`"pdf-file-4.pdf`	`"Specification #2"`

多語言

默認情況下，使用多語言單主機站點，Hugo 在構建站點時不會復制共享頁面資源。

此行為僅限於 Markdown 內容。其他 content formats 的共享頁面資源將復制到每個語言 bundle 中。

考慮此站點配置：

defaultContentLanguage: de
defaultContentLanguageInSubdir: true
languages:
  de:
    languageCode: de-DE
    languageName: Deutsch
    weight: 1
  en:
    languageCode: en-US
    languageName: English
    weight: 2

defaultContentLanguage = 'de'
defaultContentLanguageInSubdir = true
[languages]
  [languages.de]
    languageCode = 'de-DE'
    languageName = 'Deutsch'
    weight = 1
  [languages.en]
    languageCode = 'en-US'
    languageName = 'English'
    weight = 2

{
   "defaultContentLanguage": "de",
   "defaultContentLanguageInSubdir": true,
   "languages": {
      "de": {
         "languageCode": "de-DE",
         "languageName": "Deutsch",
         "weight": 1
      },
      "en": {
         "languageCode": "en-US",
         "languageName": "English",
         "weight": 2
      }
   }
}

以及此內容：

content/
└── my-bundle/
    ├── a.jpg     <-- 共享頁面資源
    ├── b.jpg     <-- 共享頁面資源
    ├── c.de.jpg
    ├── c.en.jpg
    ├── index.de.md
    └── index.en.md

使用 v0.122.0 及更早版本，Hugo 復制共享頁面資源，為每種語言創建副本：

public/
├── de/
│   ├── my-bundle/
│   │   ├── a.jpg     <-- 共享頁面資源
│   │   ├── b.jpg     <-- 共享頁面資源
│   │   ├── c.de.jpg
│   │   └── index.html
│   └── index.html
├── en/
│   ├── my-bundle/
│   │   ├── a.jpg     <-- 共享頁面資源 (重復)
│   │   ├── b.jpg     <-- 共享頁面資源 (重復)
│   │   ├── c.en.jpg
│   │   └── index.html
│   └── index.html
└── index.html

使用 v0.123.0 及更高版本，Hugo 將共享資源放在默認內容語言的頁面 bundle 中：

public/
├── de/
│   ├── my-bundle/
│   │   ├── a.jpg     <-- 共享頁面資源
│   │   ├── b.jpg     <-- 共享頁面資源
│   │   ├── c.de.jpg
│   │   └── index.html
│   └── index.html
├── en/
│   ├── my-bundle/
│   │   ├── c.en.jpg
│   │   └── index.html
│   └── index.html
└── index.html

這種方法減少了構建時間、存儲需求、帶寬消耗和部署時間，最終降低成本。

要將 Markdown 鏈接和圖像目標解析到正確位置，你必須使用鏈接和圖像渲染鉤子，使用 Resources.Get 方法捕獲頁面資源，然後調用其 RelPermalink 方法。

在默認配置中，Hugo 自動使用 embedded link render hook 和 embedded image render hook 用於多語言單主機站點，特別是當 duplication of shared page resources 功能被禁用時。這是此類站點的默認行為。如果項目、模塊或主題定義了自定義鏈接或圖像渲染鉤子，將使用這些鉤子。

你還可以配置 Hugo always 使用嵌入式鏈接或圖像渲染鉤子，僅作為 fallback 使用，或 never 使用。參見詳情。

雖然復制共享頁面資源效率低下，但如果需要，你可以在站點配置中啟用此功能：

markup:
  goldmark:
    duplicateResourceFiles: true

[markup]
  [markup.goldmark]
    duplicateResourceFiles = true

{
   "markup": {
      "goldmark": {
         "duplicateResourceFiles": true
      }
   }
}

Last updated: January 1, 0001

Improve this page

示例

元數據

資源元數據示例

name 和 title 中的 :counter 佔位符

多語言

`name` 和 `title` 中的 `:counter` 佔位符