Hugo Next主题文章路径修改指南

1. 问题背景

使用 Hugo Next 主题时,默认文章存放在 content/post 目录下,构建后的文章 URL 通常为:

1
https://fungzhenhua.github.io/post/文章名/

由于站点发布到 fungzhenhua.github.io(GitHub Pages 用户主页),希望文章直接以根目录形式访问:

1
https://fungzhenhua.github.io/文章名/

而不是所有文章都带有 /post/ 前缀。


2. 核心思路

不需要移动 content/post 目录,而是通过修改 Hugo 的 permalinks(永久链接) 配置来控制生成路径。

Hugo 会根据 permalinks 规则,将 content/post 下的文章映射到指定 URL 结构。


3. 将文章路径修改到根目录

在 Hugo 站点根目录下找到配置文件,通常是以下之一:

  • hugo.yaml
  • hugo.toml
  • config.yaml

3.1 使用 hugo.yaml

添加或修改:

1
2
3
4
5
permalinks:
  page:
    post: /:slug/
  section:
    post: /

3.2 使用 hugo.toml

添加或修改:

1
2
3
4
5
[permalinks.page]
post = "/:slug/"

[permalinks.section]
post = "/"

3.3 使用 config.yaml

添加或修改:

1
2
permalinks:
  posts: /:filename

说明:不同 Hugo 版本和配置格式对 permalinks 的写法支持略有差异,推荐优先使用 hugo.yaml 或 hugo.toml 中的 page 与 section 规则。

配置完成后,重新运行:

1
hugo

生成的 public 目录中,文章路径就会从:

1
/post/文章名/

变为:

1
/文章名/

4. 按文章日期生成目录(类似 Hexo)

如果希望像 Hexo 一样,按文章建立日期生成“年/月/日”目录,并加入文章路径,可以继续修改 permalinks。

4.1 修改 hugo.yaml

1
2
3
4
5
permalinks:
  page:
    post: /:year/:month/:day/:slug/
  section:
    post: /

这样,一篇日期为 2026-11-17、文件名为 my-article.md 的文章,构建后的路径会变成:

1
/2026/11/17/my-article/

完整访问地址类似:

1
https://fungzhenhua.github.io/2026/11/17/my-article/

4.2 修改 hugo.toml

1
2
3
4
5
[permalinks.page]
post = "/:year/:month/:day/:slug/"

[permalinks.section]
post = "/"

5. Hugo 日期令牌说明

Hugo 提供了多种日期令牌,可以自由组合到 permalinks 中。

令牌含义示例(日期:2026-11-17)
:year4 位年份2026
:month2 位月份11
:monthname月份英文名November
:day2 位日期17
:yearday一年中的第几天321
:weekday星期(Sunday=0)2(周二)
:weekdayname星期英文名Tuesday

注意:这些日期令牌的值来源于文章 Front Matter 中的 date 字段,而不是文件的创建时间或修改时间。


6. 路径最后一段的选择

配置中的 :slug 可以替换为其他令牌:

  • :slug:优先使用 Front Matter 中的 slug 字段,没有则回退到标题。
  • :contentbasename:直接使用内容文件的基名,行为更稳定可控。
  • :title:使用文章标题。

推荐使用:

1
2
3
4
5
permalinks:
  page:
    post: /:year/:month/:day/:contentbasename/
  section:
    post: /

这样路径最后一段与 Markdown 文件名一致,避免标题变化导致 URL 不稳定。


7. 在文章 Front Matter 中单独设置路径

如果只有少量文章需要特殊路径,可以直接在文章 Markdown 文件顶部的 Front Matter 中设置 url 或 slug。

7.1 设置 url(完全覆盖)

1
2
3
4
---
title: "你的文章标题"
url: "你的文章路径"
---

url 会完全覆盖整个文章路径。

7.2 设置 slug(覆盖路径最后一段)

1
2
3
4
---
title: "你的文章标题"
slug: "你的文章路径"
---

slug 只覆盖路径的最后一段。

注意:如果同时定义了 permalinks,permalinks 的规则会优先于 slug,但 url 的优先级最高。


8. 关于 GitHub Pages 的说明

站点发布到 fungzhenhua.github.io,这是一个 GitHub Pages 用户主页,网站本身就部署在根域名下。

因此:

  • 不需要额外设置 baseURL 的子路径,例如 https://fungzhenhua.github.io/blog/。
  • 只要按照上述方法修改 permalinks,Hugo 生成的页面链接就会自然变成:
1
https://fungzhenhua.github.io/文章/

或按日期路径:

1
https://fungzhenhua.github.io/2026/11/17/文章/

9. 最终推荐配置

如果希望文章直接位于根目录,并按日期分层,推荐使用以下配置。

hugo.yaml

1
2
3
4
5
permalinks:
  page:
    post: /:year/:month/:day/:slug/
  section:
    post: /

或者使用更稳定的文件名作为路径最后一段:

1
2
3
4
5
permalinks:
  page:
    post: /:year/:month/:day/:contentbasename/
  section:
    post: /

修改配置后,重新执行:

1
hugo

即可生成新的文章路径结构。