HUGO 中文文档

  • 新闻
  • 文档
  • 主题
  • 社区
  • GitHub
gohugoio Star
  • 关于
    • 本节内容
    • 简介
    • 特性
    • 隐私
    • 安全
    • 许可证
  • 安装
    • 本节内容
    • macOS
    • Linux
    • Windows
    • BSD
  • 快速上手
    • 本节内容
    • 快速入门
    • 基本用法
    • 目录结构
    • 配置
    • 配置标记
    • 术语表
    • 配置构建
    • 外部学习资源
  • 快速参考
    • 本节内容
    • 表情符号
    • 函数
    • 方法
    • 页面集合
  • 内容管理
    • 本节内容
    • 组织
    • 页面包
    • 内容格式
    • Front matter (前置 matter)
    • 构建选项
    • 页面资源
    • 图片处理
    • 短代码
    • 相关内容
    • 章节
    • 内容类型
    • 原型
    • 分类法
    • 摘要
    • 链接和交叉引用
    • URL 管理
    • 菜单
    • 评论
    • 多语言
    • Markdown 属性
    • 语法高亮
    • 图表
    • 数学公式
    • 数据源
    • 内容适配器
  • 模板
    • 本节内容
    • 简介
    • 模板类型
    • 查找顺序
    • 基模板
    • 首页模板
    • 单个模板
    • 章节模板
    • 分类模板
    • 术语模板
    • 局部模板
    • 内容视图模板
    • 短代码模板
    • 站点地图模板
    • RSS 模板
    • 404 模板
    • robots.txt 模板
    • 菜单
    • 分页
    • 内嵌模板
    • 自定义输出格式
  • 函数
    • 本节内容
    • css
    • fmt
    • go 模板
    • hugo
    • js
    • lang
    • openapi3
    • os
    • urls
    • 全局
    • 加密
    • 反射
    • 变形
    • 变换
    • 哈希
    • 图像
    • 图表函数
    • 字符串
    • 安全函数
    • 局部模板函数
    • 数学
    • 数据
    • 时间
    • 模板
    • 比较
    • 类型转换
    • 编码
    • 调试
    • 资源
    • 路径
    • 集合
  • 方法
    • 本节内容
    • Duration
    • Menu
    • Page
    • Pager
    • Resource
    • Shortcode
    • Site
    • Taxonomy
    • Time
    • 菜单项
    • 页面
  • 渲染钩子
    • 本节内容
    • 简介
    • 块引用
    • 代码块
    • 标题
    • Images
    • 链接
    • Passthrough
    • 表格
  • Hugo 模块
    • 本节内容
    • 配置 Hugo 模块
    • 使用 Hugo 模块
    • 主题组件
  • Hugo 管道
    • 本节内容
    • 简介
    • 将 Sass 编译为 CSS
    • PostCSS
    • PostProcess
    • JavaScript 构建
    • 资源压缩
    • 连接资产
    • 指纹和 SRI 哈希
    • 从字符串创建资源
    • 从模板创建资源
  • 命令行界面
  • 故障排除
    • 本节内容
    • Audit
    • 日志记录
    • 检查
    • 弃用
    • 性能
    • FAQs
  • 开发者工具
    • 本节内容
    • 编辑器插件
    • 前端
    • Search
    • 迁移
    • 其他项目
  • 托管和部署
    • 本节内容
    • Hugo 部署
    • 使用 Rclone 部署
    • 使用 Rsync 部署
    • 在 21YunBox 上托管
    • 在 AWS Amplify 上托管
    • 在 Cloudflare Pages 上托管
    • 在 Firebase 上托管
    • 在 GitLab Pages 上托管
    • 在 Netlify 上托管
    • 在 Render 上托管
    • 托管在 Azure 静态 Web 应用上
    • 托管在 GitHub Pages 上
    • 托管在 KeyCDN 上
  • 贡献
    • 本节内容
    • 开发
    • 文档
    • 主题
  • 维护
CONTENT MANAGEMENT

页面资源

使用页面资源将资源与页面逻辑地关联起来。

页面资源只能从 页面包 访问,这些目录在其根目录下具有 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 (页面包根目录)

示例

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

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

捕获资源后,使用任何适用的 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 "无法获取页面资源 %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>图书:</p>
    <ul>
      {{ range . }}
        <li>{{ .title }}</li>
      {{ end }}
    </ul>
  {{ end }}
{{ else }}
  {{ errorf "无法获取页面资源 %q" $path }}
{{ end }}

元数据

页面资源的元数据由相应页面的前置 matter 中名为 resources 的数组/表参数管理。您可以使用 通配符 批量分配值。

类型为 page 的资源从其自身的前置 matter 获取 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: 照片规格
- src: documents/guide.pdf
  title: 使用指南
- src: documents/checklist.pdf
  title: 文档清单
- src: documents/payment.docx
  title: 付款证明
- 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 = '照片规格'
  [resources.params]
    icon = 'photo'
[[resources]]
  src = 'documents/guide.pdf'
  title = '使用指南'
[[resources]]
  src = 'documents/checklist.pdf'
  title = '文档清单'
[[resources]]
  src = 'documents/payment.docx'
  title = '付款证明'
[[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": "照片规格"
      },
      {
         "src": "documents/guide.pdf",
         "title": "使用指南"
      },
      {
         "src": "documents/checklist.pdf",
         "title": "文档清单"
      },
      {
         "src": "documents/payment.docx",
         "title": "付款证明"
      },
      {
         "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 是 resources 的 name 和 title 参数中识别的特殊占位符。

当它们第一次在 name 或 title 中使用时,计数器从 1 开始。

例如,如果一个包具有资源 photo_specs.pdf 、 other_specs.pdf 、 guide.pdf 和 checklist.pdf ,并且前置 matter 已将 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 在构建站点时不会复制共享页面资源。

此行为仅限于 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     <-- 共享页面资源
    ├── 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

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

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

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

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

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

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

See also

  • 组织
  • EXIF
  • js.Build
  • os.Getenv
  • transform.Highlight

On this page

  • 示例
  • 元数据
  • 多语言
Last updated: January 10, 2025: 添加 gtm 谷歌代码管理 (6220bf5)
Improve this page
By the Hugo Authors
Hugo Logo
  • File an Issue
  • Get Help
  • @GoHugoIO
  • @spf13
  • @bepsays
 

Hugo Sponsors

Your Company?
 

The Hugo logos are copyright © Steve Francia 2013–2025.

The Hugo Gopher is based on an original work by Renée French.

  • 新闻
  • 文档
  • 主题
  • 社区
  • GitHub
  • 关于
  • 安装
  • 快速上手
  • 快速参考
  • 内容管理
  • 模板
  • 函数
  • 方法
  • 渲染钩子
  • Hugo 模块
  • Hugo 管道
  • 命令行界面
  • 故障排除
  • 开发者工具
  • 托管和部署
  • 贡献
  • 维护