Featured image of post Hugo文章引用完整指南
Hugo

Hugo文章引用完整指南

在Hugo中，文章之间的相互引用是提高用户体验和SEO的重要功能。本文将详细介绍各种文章引用方法。

-- 次浏览
-- 条评论

Hugo文章引用完整指南

在Hugo中，文章之间的相互引用是提高用户体验和SEO的重要功能。本文将详细介绍各种文章引用方法。

1. 基础引用方法

1.1 使用 ref shortcode（推荐）

ref shortcode 是Hugo内置的引用功能，会生成绝对链接：

1

{{< ref "/post/path/to/article.md" >}}

优点：

  • 自动生成正确的链接
  • 构建时会检查链接有效性
  • 支持多语言
  • 支持锚点引用

示例：

1

查看这篇文章：[WordPress使用git-it-write插件](/post/wordpress/wordpress使用git-it-write插件配合github自动发布markdown/)

1.2 使用 relref shortcode

relref 生成相对链接，适合站点迁移：

1

{{< relref "/post/path/to/article.md" >}}

1.3 直接使用 Markdown 链接

1

[文章标题](/post/article-slug/)

2. 高级引用技巧

2.1 引用特定章节

可以引用文章中的特定章节：

1

{{< ref "/post/article.md#section-title" >}}

2.2 引用文章并显示链接文本

1

[显示的文本]({{< ref "/post/article.md" >}})

2.3 在链接中使用变量

1

{{< ref "/post/article.md" >}}

2.4 直接 URL、ref 与 post-ref 怎么选

本仓库当前三种写法都存在，但适用场景并不一样：

直接写 URL

1

[AI 编程 CLI 工具怎么选：Claude Code、Codex CLI 与 OpenCode 对比](/ai/ai-cli-tools-comparison/)

适合场景：

  • 系列总览页、导航页
  • 已经显式设置 url，且路径长期稳定的文章
  • 希望源码一眼就能看懂最终跳转地址的场景

特点：

  • 优点是直观、简洁
  • 缺点是目标文章如果改了 url，这里不会自动跟着改

使用 ref

1

[相关文章]({{< ref "/post/nas/video/视频资源术语完全指南.md" >}})

适合场景：

  • 正文里的自然文本互链
  • 希望链接跟随目标文章 url 或 slug 自动变化
  • 需要 Hugo 在构建阶段帮助检查链接有效性的场景

特点：

  • 优点是绑定内容文件，不直接绑定发布 URL
  • 缺点是源码可读性不如直接 URL，目标文件移动后要同步改路径

使用 post-ref

1

{{< post-ref "post/nas/video/视频资源术语完全指南.md" >}}

适合场景：

  • 某段正文后面插入“扩展阅读”
  • 希望展示标题、摘要、日期、分类的引用卡片
  • 一篇文章里少量、重点地推荐相关文章

特点：

  • 本质上也是先按内容路径找到页面，再输出当前真实链接
  • 更适合重点推荐，不适合在正文中高频重复插入

当前仓库的建议

如果只是正文里顺手提一句相关文章，优先用 ref。

如果是想在段落后面显式推荐一篇扩展阅读，优先用 post-ref。

如果是系列总览、专题导航，且目标文章 URL 结构已经稳定，直接写 URL 也完全可以。

3. 自定义引用卡片

我们还可以创建自定义的引用卡片来美化文章引用：

3.1 创建 shortcode

创建 layouts/shortcodes/post-ref.html：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

{{- $ref := .Get 0 -}}
{{- $page := .Site.GetPage $ref -}}
{{- if $page -}}
<div class="post-reference-card">
    <a href="{{ $page.RelPermalink }}" class="post-ref-link">
        <div class="post-ref-content">
            <h3 class="post-ref-title">{{ $page.Title }}</h3>
            <p class="post-ref-summary">{{ $page.Summary | truncate 150 }}</p>
            <div class="post-ref-meta">
                <span class="post-ref-date">{{ $page.Date.Format "2006-01-02" }}</span>
                {{- if $page.Params.categories -}}
                <span class="post-ref-category">{{ delimit $page.Params.categories ", " }}</span>
                {{- end -}}
            </div>
        </div>
    </a>
</div>
{{- end -}}

3.2 使用自定义引用卡片

1

{{< post-ref "post/wordpress/WordPress使用git-it-write插件配合github自动发布markdown.md" >}}

4. 相关文章功能

Hugo Stack 主题已经内置了相关文章功能，会自动在文章末尾显示相关文章：

4.1 配置相关文章

在 hugo.yaml 中配置：

1
2
3
4
5
6
7
8
9

related:
  includeNewer: true
  threshold: 60
  toLower: false
  indices:
    - name: tags
      weight: 100
    - name: categories
      weight: 200

4.2 在文章中手动指定相关文章

在Front Matter中添加：

1
2
3

related:
  - "/post/article-1.md"
  - "/post/article-2.md"

5. 最佳实践

5.1 文件组织

建议按分类组织文章：

1
2
3
4
5
6
7
8

content/post/
├── hugo/
│   ├── hugo基础教程.md
│   └── hugo高级技巧.md
├── wordpress/
│   └── wordpress插件推荐.md
└── tools/
    └── 开发工具推荐.md

5.2 引用规范

  1. 使用内容路径：post-ref 传入相对于 content/ 的文章路径，例如 post/nas/video/视频资源术语完全指南.md
  2. 检查链接有效性：构建时会自动检查 ref 和 relref 的有效性
  3. 统一命名规范：使用一致的文件命名规范
  4. 添加描述性文本：不要直接暴露链接，添加有意义的描述

5.3 性能优化

  1. 使用缓存：Hugo会缓存引用结果
  2. 避免循环引用：不要创建文章间的循环引用
  3. 批量引用：在一篇文章中引用多个相关文章

6. 常见问题

6.1 引用失败

错误信息：

1

ERROR REF_NOT_FOUND: Ref "article.md": page not found

解决方法：

  1. 检查文件路径是否正确
  2. 确认文件是否存在
  3. post-ref 使用 post/... 这种内容路径，确认目标文件真实存在

6.2 中文文件名问题

对于中文文件名，Hugo会自动处理，但建议在链接中使用英文slug：

1
2
3

# Front Matter
title: "中文标题"
slug: "english-slug"

6.3 多语言支持

如果使用多语言，引用时需要指定语言：

1

{{< ref "/post/article.zh-cn.md" >}}

总结

Hugo提供了多种文章引用方式，选择合适的方法可以提高用户体验和维护效率：

  1. 日常引用：使用 ref shortcode
  2. 美观展示：使用自定义引用卡片
  3. 自动推荐：配置相关文章功能
  4. 性能优化：遵循最佳实践

通过合理使用这些引用功能，可以构建一个互联互通的知识体系，提高读者的阅读体验。

相关文章

WordPress使用git-it-write插件配合github自动发布markdown

WordPress安装git-it-write插件连接GitHub仓库，实现Markdown文件自动同步发布，打造基于Git的WordPress内容管理工作流，程序员友好的博客发布方案。

2025-04-06wordpress

Typora使用picgo-core配置上传图片到easyimage图床

Typora编辑器集成PicGo-Core自动上传图片到EasyImage图床，配置图床API和上传规则，实现Markdown写作图片自动上传和管理的高效方案。

2025-04-05tools