Hugo如何在shortcode中正确创建指向站内页面的链接

parse failed unexpected "<" in command报错的核心原因是语法使用场景不匹配：
{{< ref "xxx" >}} 是仅适用于Markdown内容文件的shortcode调用语法，不能直接写在自定义shortcode的HTML模板文件中——shortcode模板遵循Go HTML模板解析规则，碰到不属于模板语法的<符号就会直接抛出解析失败错误。
硬编码带域名的绝对链接会和部署域名强绑定，切换测试/生产环境、修改站点部署子路径时都会出现链接失效问题，不推荐使用。

根据代码编写场景选对应写法即可：

• 在自定义shortcode的.html模板文件中生成站内链接
  直接调用Hugo内置的模板级ref/relref函数即可，使用标准Go模板语法，不要加<>标记，注意第一个参数必须传入当前页面上下文.：

  {{/* 生成适配任意部署域名/子路径的相对链接，通用性最强 */}}
  <a href="{{ relref . "page_name" }}">链接显示文本</a>
  
  {{/* 生成带站点baseURL的站内绝对路径，不会硬编码绑定域名 */}}
  <a href="{{ ref . "page_name" }}">链接显示文本</a>
  

  两个函数会自动读取站点配置里的baseURL参数，不管部署到什么域名、什么子路径下，都会生成正确的链接地址，适配所有部署场景。
• 如果是在Markdown内容中调用自定义shortcode时需要传站内链接参数
  不要直接把{{< ref >}}嵌套写在shortcode参数位，可以直接在shortcode模板内部接收页面路径参数，再用上述relref/ref方法生成链接。比如自定义名为mylink的shortcode，调用方式为{{< mylink "page_name" "点我跳转" >}}，模板内代码写为：

  <a href="{{ relref . (.Get 0) }}">{{ .Get 1 }}</a>
  

如果调用函数时提示找不到对应页面，检查传入的页面标识是否正确：支持传入页面的完整相对路径（比如/posts/2024/hello-world/）、页面逻辑名，不需要带.md后缀。

内容的提问来源于stack exchange，提问作者res1