这是本节的多页打印视图。 点击此处打印.

返回本页常规视图.

Hugo模块

Hugo Modules - Hugo 模块

https://gohugo.io/hugo-modules/

​ Hugo 模块是 Hugo 的核心构建块。一个模块可以是您的主项目或一个较小的模块,提供 Hugo 中定义的 7 种组件类型之一或多个组件类型:staticcontentlayoutsdataassetsi18narchetypes

​ 您可以以任何组合方式组合模块,甚至挂载来自非 Hugo 项目的目录,形成一个大的虚拟联合文件系统。

​ Hugo 模块由 Go 模块驱动。有关 Go 模块的更多信息,请参见:

​ 这一切都是全新的,只有很少几个示例项目:

1 - 配置模块

Configure Modules - 配置模块

https://gohugo.io/hugo-modules/configuration/

​ 本页描述了模块的配置选项。

模块配置:Top level -> [module]

config.

=== “yaml”

```yaml
module:
  noProxy: none
  noVendor: ""
  private: '*.*'
  proxy: direct
  replacements: ""
  workspace: "off"
```

=== “toml”

```toml
[module]
  noProxy = 'none'
  noVendor = ''
  private = '*.*'
  proxy = 'direct'
  replacements = ''
  workspace = 'off'
```

=== “json”

```json
{
   "module": {
      "noProxy": "none",
      "noVendor": "",
      "private": "*.*",
      "proxy": "direct",
      "replacements": "",
      "workspace": "off"
   }
}
```

noVendor

​ 一个可选的 Glob 模式,用于匹配在vendoring时跳过的模块路径,例如"github.com/**"

vendorClosest

​ 当启用时,我们将选择与使用它的模块最接近的vendored模块。默认行为是选择第一个。请注意,每个给定模块路径仍然只能有一个依赖项,因此一旦使用它,就无法重新定义它。

proxy

​ 定义用于下载远程模块的代理服务器。默认值为 direct,表示"git clone"等。

noProxy

​ 逗号分隔的 glob 列表,匹配不应使用上述配置的代理的路径。

private

​ 逗号分隔的 glob 列表,匹配应视为私有的路径。

workspace

​ 要使用的工作区文件。这启用了 Go 工作区模式。请注意,这也可以通过操作系统 env 设置,例如 export HUGO_MODULE_WORKSPACE=/my/hugo.work。这仅适用于 Go 1.18+。在 Hugo v0.109.0 中,我们将默认设置为 off,并且现在会将任何相对的工作文件名解析为相对于工作目录。

replacements

​ 从模块路径到目录的映射的逗号分隔列表,例如 github.com/bep/my-theme -> ../..,github.com/bep/shortcodes -> /some/path。这对于临时本地开发模块非常有用,在这种情况下,您可能希望将其保存为环境变量,例如:env HUGO_MODULE_REPLACEMENTS="github.com/bep/my-theme -> ../.."。相对路径相对于 themesDir。允许使用绝对路径。

​ 请注意,上述术语直接映射到 Go 模块中的对应项。设置其中的一些可能会自然地设置为操作系统环境变量。例如,要设置要使用的代理服务器:

1
env HUGO_MODULE_PROXY=https://proxy.example.org hugo

​ Hugo 模块的大多数命令需要安装更新版本的 Go(请参阅 https://golang.org/dl/)和相关的 VCS 客户端(例如 Git,请参阅 https://git-scm.com/downloads/)。如果您在 Netlify 上运行"旧"站点,则可能必须在环境设置中将 GO_VERSION 设置为 1.12。

​ 有关 Go 模块的更多信息,请参见:

模块配置:hugoVersion -> [module.hugoVersion]

​ 如果您的模块需要特定版本的Hugo才能正常工作,您可以在module部分中指示,并且如果使用过于旧或新的版本,用户将收到警告。

config.

=== “yaml”

```yaml
module:
  hugoVersion:
    extended: false
    max: ""
    min: ""
```

=== “toml”

```toml
[module]
  [module.hugoVersion]
    extended = false
    max = ''
    min = ''
```

=== “json”

```json
{
   "module": {
      "hugoVersion": {
         "extended": false,
         "max": "",
         "min": ""
      }
   }
}
```

​ 以上任何内容均可省略。

min

​ 支持的最低Hugo版本,例如0.55.0

max

​ 支持的最高Hugo版本,例如0.55.0

extended

​ 是否需要Hugo的扩展版本。

模块配置:imports ->[[module.imports]]

config.

=== “yaml”

```yaml
module:
  imports:
  - disable: false
    ignoreConfig: false
    ignoreImports: false
    path: github.com/gohugoio/hugoTestModules1_linux/modh1_2_1v
  - path: my-shortcodes
```

=== “toml”

```toml
[module]
[[module.imports]]
  disable = false
  ignoreConfig = false
  ignoreImports = false
  path = 'github.com/gohugoio/hugoTestModules1_linux/modh1_2_1v'
[[module.imports]]
  path = 'my-shortcodes'
```

=== “json”

```json
{
   "module": {
      "imports": [
         {
            "disable": false,
            "ignoreConfig": false,
            "ignoreImports": false,
            "path": "github.com/gohugoio/hugoTestModules1_linux/modh1_2_1v"
         },
         {
            "path": "my-shortcodes"
         }
      ]
   }
}
```

path

​ 可以是一个有效的 Go 模块路径,例如 github.com/gohugoio/myShortcodes,或者是存储在您主题文件夹中的模块目录名称。

ignoreConfig

​ 如果启用,将不会加载任何模块配置文件,例如 config.toml。请注意,这也会停止加载任何传递模块依赖项。

ignoreImports

​ 如果启用,将不跟随模块导入。

disable

​ 将其设置为true以禁用该模块,同时保留go.*文件中的任何版本信息。

noMounts

​ 不要在此导入中挂载任何文件夹。

noVendor

​ 永远不要将此导入内容纳入 vendor(仅允许在主项目中)。

​ 大多数Hugo模块命令需要安装更新的Go版本(请参见https://golang.org/dl/)和相关的VCS客户端(例如Git,请参见https://git-scm.com/downloads/)。如果您在Netlify上运行"旧"站点,则可能需要在环境设置中将GO_VERSION设置为1.12。

​ 有关Go模块的更多信息,请参见:

模块配置:mounts -> [[module.mounts]]

​ 在Hugo 0.56.0中引入mounts配置时,我们小心地保留了现有的contentDirstaticDir等配置,以确保所有现有站点都能继续工作。但是,您不应同时使用两者:如果您添加了mounts部分,则应删除旧的contentDirstaticDir等设置。

​ 当您添加mount时,有关目标根目录的默认mount将被忽略:请确保明确添加它。

默认挂载点

config.

=== “yaml”

```yaml
module:
  mounts:
  - source: content
    target: content
  - source: static
    target: static
  - source: layouts
    target: layouts
  - source: data
    target: data
  - source: assets
    target: assets
  - source: i18n
    target: i18n
  - source: archetypes
    target: archetypes
```

=== “toml”

```toml
[module]
[[module.mounts]]
  source = 'content'
  target = 'content'
[[module.mounts]]
  source = 'static'
  target = 'static'
[[module.mounts]]
  source = 'layouts'
  target = 'layouts'
[[module.mounts]]
  source = 'data'
  target = 'data'
[[module.mounts]]
  source = 'assets'
  target = 'assets'
[[module.mounts]]
  source = 'i18n'
  target = 'i18n'
[[module.mounts]]
  source = 'archetypes'
  target = 'archetypes'
```

=== “json”

```json
{
   "module": {
      "mounts": [
         {
            "source": "content",
            "target": "content"
         },
         {
            "source": "static",
            "target": "static"
         },
         {
            "source": "layouts",
            "target": "layouts"
         },
         {
            "source": "data",
            "target": "data"
         },
         {
            "source": "assets",
            "target": "assets"
         },
         {
            "source": "i18n",
            "target": "i18n"
         },
         {
            "source": "archetypes",
            "target": "archetypes"
         }
      ]
   }
}
```

source

挂载点的源目录。对于主项目,可以是相对于项目的路径,也可以是绝对路径,甚至可以是符号链接。对于其他模块,它必须是相对于项目的路径。

target

它应该被挂载到Hugo虚拟文件系统中的位置。它必须以Hugo的组件文件夹之一开头:staticcontentlayoutsdataassetsi18narchetypes。例如,content/blog

lang

语言代码,例如"en"。只适用于content挂载和多主机模式下的static挂载。

includeFiles (string or slice)

​ 一个或多个用于匹配要包括的文件或目录的glob(通配符)。如果未设置excludeFiles,则与includeFiles匹配的文件将被挂载。

​ 这些通配符从source根开始匹配文件名,它们应该使用Unix样式的斜杠,即使在Windows上也是如此。 /匹配挂载点根目录,**可以用作超级星号以递归匹配所有目录,例如/posts/**.jpg

​ 搜索时忽略大小写。

excludeFiles (字符串或切片)

​ 一个或多个用于匹配要排除的文件的通配符。

示例

config.

=== “yaml”

```yaml
module:
  mounts:
  - excludeFiles: docs/*
    source: content
    target: content
```

=== “toml”

```toml
[module]
[[module.mounts]]
  excludeFiles = 'docs/*'
  source = 'content'
  target = 'content'
```

=== “json”

```json
{
   "module": {
      "mounts": [
         {
            "excludeFiles": "docs/*",
            "source": "content",
            "target": "content"
         }
      ]
   }
}
```

参见

2 - 使用 Hugo 模块

Use Hugo Modules - 使用 Hugo 模块

https://gohugo.io/hugo-modules/use-modules/

​ 如何使用 Hugo 模块来构建和管理您的站点。

先决条件

​ 大多数 Hugo 模块的命令需要安装更新版本的 Go(请参阅 https://golang.org/dl/)和相关的 VCS 客户端(例如 Git,请参阅 https://git-scm.com/downloads/)。如果您在 Netlify 上运行的是"旧"站点,则可能需要在环境设置中将 GO_VERSION 设置为 1.12。

​ 有关 Go 模块的更多信息,请参见:

初始化新模块

​ 使用 hugo mod init 初始化一个新的 Hugo 模块。如果它无法猜测模块路径,您必须提供它作为参数,例如:

1
hugo mod init github.com/gohugoio/myShortcodes

​ 另请参阅 CLI 文档

为主题使用模块

​ 使用模块作为主题的最简单方法是在配置中导入它。

  1. 初始化 hugo 模块系统:hugo mod init github.com/<your_user>/<your_project>
  2. 导入主题:

config.

=== “yaml”

```yaml
module:
  imports:
  - path: github.com/spf13/hyde
```

=== “toml”

```toml
[module]
[[module.imports]]
  path = 'github.com/spf13/hyde'
```

=== “json”

```json
{
   "module": {
      "imports": [
         {
            "path": "github.com/spf13/hyde"
         }
      ]
   }
}
```

更新模块

​ 将模块作为导入项添加到您的配置文件时,模块将被下载并添加,详见模块导入

​ 要更新或管理版本,可以使用 hugo mod get 命令。

​ 以下是一些示例:

更新所有模块

1
hugo mod get -u

递归更新所有模块

1
hugo mod get -u ./...

更新一个模块

1
hugo mod get -u github.com/gohugoio/myShortcodes

获取特定版本

1
hugo mod get github.com/gohugoio/myShortcodes@v1.0.7

​ 另请参阅 CLI 文档

在模块中进行更改和测试

​ 在项目中导入模块并进行本地开发的一种方法是在 go.mod 中使用replace 指令将本地目录与源代码联系起来:

1
replace github.com/bep/hugotestmods/mypartials => /Users/bep/hugotestmods/mypartials

​ 如果 hugo server正在运行,则会重新加载配置,并将 /Users/bep/hugotestmods/mypartials 添加到监视列表中。

​ 除了修改 go.mod 文件之外,您还可以使用模块配置的replacements选项。

打印依赖项图

​ 从相关的模块目录使用 hugo mod graph 命令,它将打印依赖项图,包括 vendoring、模块替换或禁用状态。

E.g.:

1
2
3
4
5
6
7
8
9
hugo mod graph

github.com/bep/my-modular-site github.com/bep/hugotestmods/mymounts@v1.2.0
github.com/bep/my-modular-site github.com/bep/hugotestmods/mypartials@v1.0.7
github.com/bep/hugotestmods/mypartials@v1.0.7 github.com/bep/hugotestmods/myassets@v1.0.4
github.com/bep/hugotestmods/mypartials@v1.0.7 github.com/bep/hugotestmods/myv2@v1.0.0
DISABLED github.com/bep/my-modular-site github.com/spf13/hyde@v0.0.0-20190427180251-e36f5799b396
github.com/bep/my-modular-site github.com/bep/hugo-fresh@v1.0.1
github.com/bep/my-modular-site in-themesdir

​ 另请参阅 CLI 文档

Vendor Your Modules

​ 运行hugo mod vendor将所有模块依赖项写入_vendor文件夹,然后在所有后续构建中使用它们。

请注意:

  • 您可以在模块树的任何级别上运行 hugo mod vendor
  • 存储在themes文件夹中的模块不会被存储到Vendoring目录中。
  • 大多数命令接受--ignoreVendorPaths标志,然后不会对与给定Glob模式匹配的模块路径使用_vendor中的供应商模块。

​ 另请参阅CLI文档

整理go.mod、go.sum

​ 运行 hugo mod tidy 以删除 go.modgo.sum 中未使用的条目。

​ 另请参阅CLI文档

清除模块缓存

​ 运行 hugo mod clean 以删除整个模块缓存。

​ 请注意,您还可以通过 maxAge 配置模块缓存,请参阅文件缓存

​ 另请参阅CLI文档

模块工作区

New in v0.109.0

Go 1.18 版本中增加了工作区支持,而 Hugo 在 v0.109.0 版本中得到了稳定的支持。

​ 工作区的常见用途是简化带有其主题模块的站点的本地开发。

​ 可以在 *.work 文件中配置工作区,并通过 module.workspace 设置激活它,对于此用法下通常由 HUGO_MODULE_WORKSPACE 操作系统环境变量控制。

​ 在Hugo 文档库中查看hugo.work文件以获取示例:

go 1.19

use .
use ../gohugoioTheme

​ 使用 use 指令,列出您要处理的所有模块,指向其相对位置。如上例所示,建议始终在列表中包括主项目(".")。

​ 有了这个指令,您可以使用启用了该工作区的Hugo服务器:

HUGO_MODULE_WORKSPACE=hugo.work hugo server --ignoreVendorPaths "**"

​ 上面添加了 --ignoreVendorPaths 标志,以忽略 _vendor 中与给定 Glob 模式匹配的模块路径中的任何存储的依赖项。如果您不使用 vendoring,则不需要该标志。但现在,服务器设置为监视工作区中的文件和目录,您可以看到重新加载本地编辑。

另请参阅

3 - 主题组件

Theme Components - 主题组件

https://gohugo.io/hugo-modules/theme-components/

​ Hugo 提供了主题组件的高级主题支持。

​ 本部分包含的信息可能已过时,并正在重写过程中。

​ 从 Hugo 0.42 版本开始,项目可以将主题配置为所需的多个主题组件的组合:

config.

=== “yaml”

```yaml
theme:
- my-shortcodes
- base-theme
- hyde
```

=== “toml”

```toml
theme = ['my-shortcodes', 'base-theme', 'hyde']
```

=== “json”

```json
{
   "theme": [
      "my-shortcodes",
      "base-theme",
      "hyde"
   ]
}
```

​ 甚至可以嵌套使用,主题组件本身可以在其 own config.toml 中包含主题组件 (主题继承)。1

​ 上述 config.toml 中的主题定义示例创建了一个具有从左到右优先级的三个主题组件的主题。

​ 对于任何给定的文件、数据条目等,Hugo 将首先查找项目,然后查找 my-shortcodesbase-theme,最后是 hyde

​ Hugo 使用两种不同的算法来合并文件系统,具体取决于文件类型:

  • 对于 i18ndata文件,Hugo 使用文件内部的翻译 ID 和数据键进行深度合并。
  • 对于static文件、layouts (templates) 和archetypes文件,这些文件在文件级别上进行合并。所以最左边的文件将被选中。

​ 上面的theme定义中使用的名称必须与 /your-site/themes 中的一个文件夹相匹配,例如 /your-site/themes/my-shortcodes。计划改进此功能,并获取 URL 方案,以便可以自动解析。

​ 还要注意,作为主题的组件可以有自己的配置文件,例如 config.toml。目前,主题组件可以配置的内容存在一些限制:

  • params (global and per language)
  • menu (global and per language)
  • outputformats and mediatypes

​ 这里也适用相同的规则:具有相同 ID 的最左边的 param/menu 等将获胜。上述内容中还存在一些隐藏的实验性命名空间支持,我们将在未来努力改进,但鼓励主题作者创建自己的命名空间,以避免命名冲突。


  1. 对于托管在 Hugo Themes Showcase中的主题组件,需要将组件添加为 git 子模块,指向目录 exampleSite/themes。 ↩︎

另请参阅