内容类型配置
通过 contentTypes 控制哪些媒体类型作为可发布资源。
这一页解决什么问题
[contentTypes] 决定「哪些媒体类型的页面资源被当作内容,从而不被单独发布」。默认六个媒体类型(Markdown、HTML、Org Mode、AsciiDoc、Pandoc、reStructuredText)都算内容。
只有一种场景需要改它:你希望把页面资源里的某个文件(例如一份 text/html 报告)像普通资源一样发布到 public/。改的时候请记住列表是整体替换的:想只移除一项,也要把其余项写全。
什么时候需要这些设置
| 设置 | 什么时候需要 | 改错了会看到什么现象 |
|---|---|---|
| 保留默认六项 | 页面资源里的标记文件只用于并入正文 | 这是默认且多数情况下正确的行为 |
移除某一项(如 text/html) |
想让该类型的页面资源被自动发布 | 移除后该资源会像普通资源一样进入 public/;若它本不该公开,等于把内部文件发布了 |
| 新增自定义媒体类型 | 站点使用别的标记格式,并希望按内容处理 | 媒体类型字符串与媒体类型配置不一致 → 配置不匹配任何文件,该资源仍会被发布,且不报错 |
支持的内容格式
Hugo 0.144.0 及更高版本支持六种内容格式:
| 内容格式 | 媒体类型 | 标识符 | 文件扩展名 |
|---|---|---|---|
| Markdown | text/markdown |
markdown |
markdown、md、mdown |
| HTML | text/html |
html |
htm、html |
| Emacs Org Mode | text/org |
org |
org |
| AsciiDoc | text/asciidoc |
asciidoc |
ad、adoc、asciidoc |
| Pandoc | text/pandoc |
pandoc |
pandoc、pdc |
| reStructuredText | text/rst |
rst |
rst |
这些格式既可以作为页面内容,也可以作为页面资源。作为页面资源时,它们的资源类型是 page。
看一个页面包的例子:
content/
└── example/
├── index.md <-- content
├── a.adoc <-- resource (resource type: page)
├── b.html <-- resource (resource type: page)
├── c.md <-- resource (resource type: page)
├── d.org <-- resource (resource type: page)
├── e.pdc <-- resource (resource type: page)
├── f.rst <-- resource (resource type: page)
├── g.jpg <-- resource (resource type: image)
└── h.png <-- resource (resource type: image)index.md 是该页面的内容,其余文件都是页面资源。文件 a 到 f 的资源类型是 page,g 与 h 的资源类型是 image。
构建站点时,Hugo 不会发布资源类型为 page 的页面资源。上面站点构建的结果是:
public/
├── example/
│ ├── g.jpg
│ ├── h.png
│ └── index.html
└── index.html多数情况下这一默认行为是合适的:含有标记语言内容的页面资源通常是为了并入主内容而存在,单独发布它们一般没有意义。
contentTypes 配置
默认行为由 contentTypes 配置决定,默认配置如下:
[contentTypes]
'text/asciidoc' = {}
'text/html' = {}
'text/markdown' = {}
'text/org' = {}
'text/pandoc' = {}
'text/rst' = {}对应关系如下:
| 键名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
contentTypes |
map |
上表六个媒体类型 | 列出的媒体类型对应的页面资源会被赋予 page 资源类型,并且不会被自动发布。 |
text/asciidoc |
map |
{} |
AsciiDoc 内容。 |
text/html |
map |
{} |
HTML 内容。 |
text/markdown |
map |
{} |
Markdown 内容。 |
text/org |
map |
{} |
Emacs Org Mode 内容。 |
text/pandoc |
map |
{} |
Pandoc 内容。 |
text/rst |
map |
{} |
reStructuredText 内容。 |
在这一默认配置下,具有上述媒体类型的页面资源会被赋予 page 资源类型,并且不会被自动发布。若想把某个媒体类型的资源类型从 page 改为 text,只需从列表中移除对应条目。
例如,把 text/html 文件的资源类型设为 text,从而允许其被自动发布,就要移除 text/html 条目:
[contentTypes]
'text/asciidoc' = {}
'text/markdown' = {}
'text/org' = {}
'text/pandoc' = {}
'text/rst' = {}同样的配置用 YAML 写作:
contentTypes:
text/asciidoc: {}
text/markdown: {}
text/org: {}
text/pandoc: {}
text/rst: {}改动后的效果是:text/html 资源类型的页面资源不再被赋予 page,因而会像普通资源一样被发布到 public 目录中。
常见坑
| 症状 | 真因 | 怎么修 |
|---|---|---|
只想放行 text/html,结果其它类型的资源也被发布了 |
列表是整体替换,其余五项没写回 | 参照本页示例,把 text/asciidoc、text/markdown、text/org、text/pandoc、text/rst 一并保留 |
改了配置,public/ 里仍没有该文件 |
媒体类型字符串写法不对(大小写、斜杠)或不匹配任何文件 | 与媒体类型配置中定义的标识逐字对齐 |
页面资源里的 .md 没有出现在产物中 |
这是默认行为:text/markdown 属于内容类型,不会单独发布 |
预期结果;需要输出就在模板中通过 .Resources 取值处理 |
| 报错看不懂 | 该分区不做取值校验,多数情况下不会报错 | 用 hugo config 查看生效的 [contentTypes];仍不对见故障排查 |
更多排查入口见故障排查。