Windows 11下Docsy示例编辑链接路径错误问题咨询

问题原因 #

这是Windows系统下Hugo与Docsy模板的路径兼容性问题：Docsy生成编辑链接时，在Windows环境下会直接读取本地文件的绝对路径（带盘符的C:\格式），而非转换为仓库相对路径，导致拼接GitHub地址后出现错误路径。

修复方法 #

1. 配置文件直接指定编辑链接前缀 #

在项目根目录的config.toml中添加或修改以下配置，手动指定编辑链接的仓库路径前缀：

[params]
  repoURL = "https://github.com/google/docsy-example"
  editURL = "https://github.com/google/docsy-example/edit/main/content/"

注意：editURL的末尾要加上content/，因为Docsy默认会拼接当前页面的相对文件路径（比如en/docs/_index.md），最终生成正确的完整编辑链接。

2. 修复模板中的路径转换逻辑 #

如果配置修改无效，可以直接修改Docsy的编辑链接模板文件（路径：layouts/partials/edit-links.html），添加Windows路径转换逻辑：

{{- $filePath := .File.Path -}}
{{- // 转换Windows路径分隔符为Unix风格，并去除本地绝对路径前缀 -}}
{{- if eq os.Windows true -}}
  {{- $filePath = replace $filePath "\\" "/" -}}
  {{- // 截取content目录之后的相对路径 -}}
  {{- $filePath = index (split $filePath "content/") 1 -}}
{{- end -}}
{{- $editURL := printf "%s%s" site.Params.editURL $filePath -}}

修改后模板会自动将Windows本地路径转换为仓库相对路径。

3. 确保Hugo运行在项目根目录 #

启动Hugo时，务必切换到Docsy示例项目的根目录（比如C:\sources\site\docsy-example）再执行命令：

hugo server

避免Hugo识别到错误的工作路径，导致文件路径读取异常。

总结 #

这并非Docsy或Hugo的核心Bug，只是Windows环境下的路径处理兼容性问题，通过上述配置调整或模板修改即可完全修复。

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