Hugo 模块

主题组件

把主题拆成多个组件,通过继承与覆盖顺序组合成一套完整主题。

把主题组合起来

一个项目可以把主题配置为任意多个主题组件(theme component)的组合:

theme = ["my-shortcodes", "base-theme", "hyde"]

这种组合还可以嵌套:主题组件本身也能在自己的 hugo.toml 中引入其他主题组件,这就是主题继承(theme inheritance)。

上面的定义在 hugo.toml 中创建了一个由 3 个主题组件构成的主题,优先级从左到右排列。查找任意文件、数据条目等内容时,Hugo 会先看项目本身,然后是 my-shortcodes、base-theme,最后才是 hyde。

覆盖顺序

Hugo 会根据文件类型使用两套不同的合并算法:

文件类型 合并方式 优先级规则
i18n 与 data 文件 按文件内部的翻译 ID 与数据键深度合并 键相同时以最靠左的值为准
static、layouts(模板)与 archetypes 文件 按文件层级合并 最靠左的那份文件被选用

也就是说,内容与数据的合并发生在键的粒度上,同一份翻译表或数据文件里的不同条目可以来自不同模块;而静态文件与模板的合并发生在整个文件的粒度上,只能「整份替换」,不能把两个模板拼在一起。

名称与配置

theme 定义中使用的名称必须与站点 /themes 目录下的某个子目录同名,例如 /your-site/themes/my-shortcodes。

还需要注意,作为主题一部分的组件可以有自己的配置文件(例如 hugo.toml)。目前主题组件能够配置的内容有一些限制:

  • params(全局与各语言)
  • menu(全局与各语言)
  • outputformats 与 mediatypes

这里同样适用前述规则:ID 相同时,最靠左的参数、菜单等取值会胜出。上述命名空间支持中还留有一些隐藏且处于实验阶段的用法,官方会继续改进;同时官方也鼓励主题作者自行建立命名空间,以免名称冲突。

与模块机制的关系

主题组件的查找顺序并不是一套独立机制,而是模块导入优先级在主题上的体现:theme 中列出的组件相当于被依次导入,越靠前优先级越高,项目自身的文件则始终排在最前面。因此,覆盖主题中的某个模板,只需在项目里放置相对路径相同的文件;覆盖翻译表中某一条译文,也只需在项目里定义同一个翻译 ID。

关于模块的导入、更新与挂载,见使用模块;关于项目目录的职责划分,见目录结构。