Hugo Next主题文章路径修改指南
1. 问题背景
使用 Hugo Next 主题时,默认文章存放在 content/post 目录下,构建后的文章 URL 通常为:
| |
由于站点发布到 fungzhenhua.github.io(GitHub Pages 用户主页),希望文章直接以根目录形式访问:
| |
而不是所有文章都带有 /post/ 前缀。
2. 核心思路
不需要移动 content/post 目录,而是通过修改 Hugo 的 permalinks(永久链接) 配置来控制生成路径。
Hugo 会根据 permalinks 规则,将 content/post 下的文章映射到指定 URL 结构。
3. 将文章路径修改到根目录
在 Hugo 站点根目录下找到配置文件,通常是以下之一:
hugo.yamlhugo.tomlconfig.yaml
3.1 使用 hugo.yaml
添加或修改:
3.2 使用 hugo.toml
添加或修改:
3.3 使用 config.yaml
添加或修改:
说明:不同 Hugo 版本和配置格式对
permalinks的写法支持略有差异,推荐优先使用hugo.yaml或hugo.toml中的page与section规则。
配置完成后,重新运行:
| |
生成的 public 目录中,文章路径就会从:
| |
变为:
| |
4. 按文章日期生成目录(类似 Hexo)
如果希望像 Hexo 一样,按文章建立日期生成“年/月/日”目录,并加入文章路径,可以继续修改 permalinks。
4.1 修改 hugo.yaml
这样,一篇日期为 2026-11-17、文件名为 my-article.md 的文章,构建后的路径会变成:
| |
完整访问地址类似:
| |
4.2 修改 hugo.toml
5. Hugo 日期令牌说明
Hugo 提供了多种日期令牌,可以自由组合到 permalinks 中。
| 令牌 | 含义 | 示例(日期:2026-11-17) |
|---|---|---|
:year | 4 位年份 | 2026 |
:month | 2 位月份 | 11 |
:monthname | 月份英文名 | November |
:day | 2 位日期 | 17 |
:yearday | 一年中的第几天 | 321 |
:weekday | 星期(Sunday=0) | 2(周二) |
:weekdayname | 星期英文名 | Tuesday |
注意:这些日期令牌的值来源于文章 Front Matter 中的
date字段,而不是文件的创建时间或修改时间。
6. 路径最后一段的选择
配置中的 :slug 可以替换为其他令牌:
:slug:优先使用 Front Matter 中的slug字段,没有则回退到标题。:contentbasename:直接使用内容文件的基名,行为更稳定可控。:title:使用文章标题。
推荐使用:
这样路径最后一段与 Markdown 文件名一致,避免标题变化导致 URL 不稳定。
7. 在文章 Front Matter 中单独设置路径
如果只有少量文章需要特殊路径,可以直接在文章 Markdown 文件顶部的 Front Matter 中设置 url 或 slug。
7.1 设置 url(完全覆盖)
url 会完全覆盖整个文章路径。
7.2 设置 slug(覆盖路径最后一段)
slug 只覆盖路径的最后一段。
注意:如果同时定义了
permalinks,permalinks的规则会优先于slug,但url的优先级最高。
8. 关于 GitHub Pages 的说明
站点发布到 fungzhenhua.github.io,这是一个 GitHub Pages 用户主页,网站本身就部署在根域名下。
因此:
- 不需要额外设置
baseURL的子路径,例如https://fungzhenhua.github.io/blog/。 - 只要按照上述方法修改
permalinks,Hugo 生成的页面链接就会自然变成:
| |
或按日期路径:
| |
9. 最终推荐配置
如果希望文章直接位于根目录,并按日期分层,推荐使用以下配置。
hugo.yaml
或者使用更稳定的文件名作为路径最后一段:
修改配置后,重新执行:
| |
即可生成新的文章路径结构。