HUGO

  • 新闻
  • 文档
  • 主题
  • 社区
  • GitHub
gohugoio Star
  • 关于
    • 本节内容
    • 介绍
    • 特性
    • 隐私
    • 安全
    • 许可
  • 安装
    • 本节内容
    • macOS
    • Linux
    • Windows
    • BSD
  • 开始使用
    • 本节内容
    • 快速入门
    • 基本用法
    • 目录结构
    • 配置
    • 配置标记
    • 配置构建
    • 术语表
    • 外部学习资源
  • 快速参考
    • 本节内容
    • 表情符号
    • 函数
    • 方法
    • 页面集合
  • 内容管理
    • 本节内容
    • 组织
    • 页面包
    • 内容格式
    • 前言
    • 构建选项
    • 页面资源
    • 图像处理
    • 简码
    • 相关内容
    • 章节
    • 内容类型
    • 原型
    • 分类
    • 摘要
    • 链接和交叉引用
    • URL 管理
    • 菜单
    • 评论
    • 多语言
    • Markdown 属性
    • 语法高亮
    • 图表
    • 数学
    • 数据源
    • 内容适配器
  • 模板
    • 本节内容
    • 介绍
    • 模板类型
    • 查找顺序
    • 基础模板
    • 首页模板
    • 单页模板
    • 章节模板
    • 分类模板
    • 术语模板
    • 局部模板
    • 内容视图模板
    • 简码模板
    • 站点地图模板
    • RSS 模板
    • 404 模板
    • robots.txt 模板
    • 菜单
    • 分页
    • 嵌入式模板
    • 自定义输出格式
  • 函数
    • 本节内容
    • cast
    • collections
    • compare
    • crypto
    • css
    • data
    • debug
    • diagrams
    • encoding
    • fmt
    • global
    • go 模板
    • hash
    • hugo
    • images
    • inflect
    • js
    • lang
    • math
    • openapi3
    • os
    • partials
    • path
    • reflect
    • resources
    • safe
    • strings
    • templates
    • time
    • transform
    • urls
  • 方法
    • 本节内容
    • Duration
    • Menu
    • 菜单项
    • Page
    • Pager
    • Pages
    • Resource
    • Shortcode
    • Site
    • Taxonomy
    • Time
  • 渲染钩子
    • 本节内容
    • 介绍
    • 块引用
    • 代码块
    • 标题
    • 图像
    • 链接
    • 直通
    • 表格
  • 简码
    • 本节内容
    • 评论
    • 详情
    • 图
    • Gist
    • Highlight
    • Instagram
    • Param
    • QR
    • Ref
    • Relref
    • Vimeo
    • X
    • YouTube
  • Hugo 模块
    • 本节内容
    • 配置 Hugo 模块
    • 使用 Hugo 模块
    • 主题组件
  • Hugo Pipes
    • 本节内容
    • 介绍
    • 将 Sass 转译为 CSS
    • PostCSS
    • PostProcess
    • JavaScript 构建
    • 资源压缩
    • 连接资源
    • 指纹识别和 SRI 哈希
    • 从字符串生成资源
    • 从模板生成资源
  • CLI
  • 问题排查
    • 本节内容
    • 审计
    • 日志记录
    • 检查
    • 弃用
    • 性能
    • 常见问题解答
  • 开发者工具
    • 本节内容
    • 编辑器插件
    • 前端
    • 搜索
    • 迁移
    • 其他项目
  • 托管和部署
    • 本节内容
    • Hugo 部署
    • 使用 Rclone 部署
    • 使用 Rsync 部署
    • 在 21YunBox 上托管
    • 在 AWS Amplify 上托管
    • 在 Azure 静态 Web 应用上托管
    • 在 Cloudflare Pages 上托管
    • 在 Firebase 上托管
    • 在 GitHub Pages 上托管
    • 在 GitLab Pages 上托管
    • 在 KeyCDN 上托管
    • 在 Netlify 上托管
    • 在 Render 上托管
  • 贡献
    • 本节内容
    • 开发
    • 文档
    • 主题
  • 维护
内容管理

页面资源

使用页面资源将资产与页面进行逻辑关联。

页面资源只能从页面包访问,这些目录的根目录中包含 index.md 或 _index.md 文件。页面资源仅适用于与其绑定的页面。

在此示例中,first-post 是一个页面包,可以访问 10 个页面资源,包括音频、数据、文档、图像和视频。虽然 second-post 也是一个页面包,但它没有页面资源,也无法直接访问与 first-post 关联的页面资源。

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

示例

在 Page 对象上使用以下任何方法来捕获页面资源

  • Resources.ByType
  • Resources.Get
  • Resources.GetMatch
  • Resources.Match

捕获资源后,使用任何适用的Resource方法来返回值或执行操作。

以下示例假设有此内容结构

content/
└── example/
    ├── data/
    │  └── books.json   <-- page resource
    ├── images/
    │  ├── a.jpg        <-- page resource
    │  └── b.jpg        <-- page resource
    ├── snippets/
    │  └── text.md      <-- page resource
    └── 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 的数组/表参数。您可以使用通配符批量分配值。

类型为 page 的资源从自己的前言中获取 Title 等信息。

name
(string) 设置 Name 中返回的值。

方法 Match、Get 和 GetMatch 使用 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 设置的 Title。
  • 除了 documents/photo_specs.pdf 之外,捆绑包中的每个 PDF 都将获得 pdf 图标。
  • 所有 PDF 文件都将获得一个新的 Name。 name 参数包含一个特殊的占位符:counter,因此 Name 将为 pdf-file-1、pdf-file-2、pdf-file-3。
  • 捆绑包中的每个 docx 都将收到 word 图标。

顺序很重要;只会使用 title、name 和 params 键的第一个设置值。后续参数仅针对尚未设置的参数进行设置。在上面的示例中,.Params.icon 首先在 src = "documents/photo_specs.pdf" 中设置为 "photo"。因此,它不会被稍后设置的 src = "**.pdf" 规则覆盖为 "pdf"。

name 和 title 中的 :counter 占位符

:counter 是 name 和 title 参数 resources 中识别的特殊占位符。

计数器在首次在 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 "规范 #1"
photo_specs.pdf "pdf-file-4.pdf “规范 #2”

多语言

v0.123.0 版本新增

默认情况下,对于多语言单主机站点,Hugo 在构建站点时不会复制共享页面资源。

此行为仅限于 Markdown 内容。其他内容格式的共享页面资源会被复制到每个语言包中。

考虑以下站点配置

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     <-- shared page resource
    ├── b.jpg     <-- shared page resource
    ├── c.de.jpg
    ├── c.en.jpg
    ├── index.de.md
    └── index.en.md

在 v0.122.0 及更早版本中,Hugo 会复制共享页面资源,为每种语言创建副本

public/
├── de/
│   ├── my-bundle/
│   │   ├── a.jpg     <-- shared page resource
│   │   ├── b.jpg     <-- shared page resource
│   │   ├── c.de.jpg
│   │   └── index.html
│   └── index.html
├── en/
│   ├── my-bundle/
│   │   ├── a.jpg     <-- shared page resource (duplicate)
│   │   ├── b.jpg     <-- shared page resource (duplicate)
│   │   ├── c.en.jpg
│   │   └── index.html
│   └── index.html
└── index.html

在 v0.123.0 及更高版本中,Hugo 将共享资源放置在默认内容语言的页面包中

public/
├── de/
│   ├── my-bundle/
│   │   ├── a.jpg     <-- shared page resource
│   │   ├── b.jpg     <-- shared page resource
│   │   ├── c.de.jpg
│   │   └── index.html
│   └── index.html
├── en/
│   ├── my-bundle/
│   │   ├── c.en.jpg
│   │   └── index.html
│   └── index.html
└── index.html

这种方法可以减少构建时间、存储需求、带宽消耗和部署时间,最终降低成本。

要将 Markdown 链接和图像目标解析到正确的位置,您必须使用链接和图像渲染钩子,这些钩子使用Resources.Get方法捕获页面资源,然后调用其RelPermalink方法。

默认情况下,对于多语言单主机站点,Hugo 会启用其嵌入式链接渲染钩子和嵌入式图像渲染钩子来解析 Markdown 链接和图像目标。

您可以根据需要覆盖嵌入式渲染钩子,前提是它们按照上述方式捕获资源。

尽管复制共享页面资源效率低下,但如果需要,您可以在站点配置中启用此功能

hugo.
     
markup:
  goldmark:
    duplicateResourceFiles: true
[markup]
  [markup.goldmark]
    duplicateResourceFiles = true
{
   "markup": {
      "goldmark": {
         "duplicateResourceFiles": true
      }
   }
}

另请参阅

  • 组织
  • 块引用
  • 构建选项
  • 代码块
  • 颜色

本页内容

  • 示例
  • 元数据
  • 多语言
最后更新:2024 年 8 月 25 日:更新页面资源文档 (7c766e724)
改进此页面
由 Hugo 作者编写
Hugo Logo
  • 提交问题
  • 获取帮助
  • @GoHugoIO
  • @spf13
  • @bepsays

Netlify badge

 

Hugo 赞助商

贵公司?
 

Hugo 徽标版权归 Steve Francia 2013–2025 所有。

Hugo 地鼠基于 Renée French 的原创作品。

  • 新闻
  • 文档
  • 主题
  • 社区
  • GitHub
  • 关于
  • 安装
  • 开始使用
  • 快速参考
  • 内容管理
  • 模板
  • 函数
  • 方法
  • 渲染钩子
  • 简码
  • Hugo 模块
  • Hugo Pipes
  • CLI
  • 问题排查
  • 开发者工具
  • 托管和部署
  • 贡献
  • 维护