CONTENT MANAGEMENT

Page resources

頁面資源僅能從 頁面包 存取，這些目錄的根目錄包含 index.md 或 _index.md 文件。頁面資源僅能被與之打包的頁面訪問。

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

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

範例

使用以下方法來捕獲頁面資源：

一旦捕獲到資源，您可以使用任何適用的 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 的數組/表格參數來設定。您可以使用 通配符 批量指定值。

name
(string) 設定返回 Name 的值。
title
(string) 設定返回 Title 的值。
params
(map) 自訂的鍵值對映射。

資源元數據範例

content/example.md
      
---
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。
  • 所有除了 documents/photo_specs.pdf 的 PDF 文件會獲得 pdf 圖標。
  • 所有 PDF 文件將獲得新的 Name，name 參數中包含特殊的佔位符 :counter，因此 Name 將為 pdf-file-1、pdf-file-2、pdf-file-3。
  • 所有 docx 文件將獲得 word 圖標。

:counter 佔位符在 name 和 title 中的應用

:counter 是一個特殊的佔位符，在 resources 中的 name 和 title 參數中會被識別。

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

例如，如果一個包包含 photo_specs.pdf、other_specs.pdf、guide.pdf 和 checklist.pdf，且前置內容中指定了 resources 如下：

content/inspections/engine/index.md
      
---
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：

資源文件 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"

多語言支持

New in v0.123.0

默認情況下，在多語言單主機網站中，Hugo 不會在構建網站時重複共享頁面資源。

考慮以下網站配置：

hugo.
      
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 將共享資源放在預設內容語言的頁面包中：

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

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

雖然複製共享頁面資源效率低下，但如果需要，您可以在網站配置中啟用此功能：

hugo.
      
markup:
  goldmark:
    duplicateResourceFiles: true

[markup]
  [markup.goldmark]
    duplicateResourceFiles = true

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

延伸閱讀

Passthrough render hooks 常見問題 Frequently asked questions