链接和交叉引用
Links and Cross References - 链接和交叉引用
https://gohugo.io/content-management/cross-references/
用于创建指向文档的简码链接。
ref
和relref
简码分别显示文档的绝对和相对永久链接。
使用ref
和relref
ref
和relref
简码需要一个参数:指向内容文档的路径,带有或不带有文件扩展名,带有或不带有锚点。没有前导 /
的路径首先相对于当前页面解析,然后相对于站点的其余部分解析。
.
└── content
├── about
| ├── _index.md
| └── credits.md
├── pages
| ├── document1.md
| └── document2.md // has anchor #anchor
├── products
| └── index.md
└── blog
└── my-post.md
这些页面可以按以下方式被引用:
1
2
3
4
5
6
7
8
9
10
11
| \{\{\< ref "document2" \>\}\} // <- From pages/document1.md, relative path
\{\{\< ref "document2#anchor" \>\}\}
\{\{\< ref "document2.md" \>\}\}
\{\{\< ref "document2.md#anchor" \>\}\}
\{\{\< ref "#anchor" \>\}\} // <- From pages/document2.md
\{\{\< ref "/blog/my-post" \>\}\} // <- From anywhere, absolute path
\{\{\< ref "/blog/my-post.md" \>\}\}
\{\{\< relref "document" \>\}\}
\{\{\< relref "document.md" \>\}\}
\{\{\< relref "#anchor" \>\}\}
\{\{\< relref "/blog/my-post.md" \>\}\}
|
index.md
可以被其路径或其不带结尾 /
的所在文件夹引用。_index.md
只被其所在文件夹引用:
1
2
3
4
5
6
| \{\{\< ref "/about" \>\}\} // <- References /about/_index.md
\{\{\< ref "/about/_index" \>\}\} // Raises REF_NOT_FOUND error
\{\{\< ref "/about/credits.md" \>\}\} // <- References /about/credits.md
\{\{\< ref "/products" \>\}\} // <- References /products/index.md
\{\{\< ref "/products/index" \>\}\} // <- References /products/index.md
|
在Markdown中使用ref
或relref
生成超链接:
1
| [About](\{\{\< ref "/about" \>\}\} "About Us")
|
如果文档无法被唯一解析,Hugo将发出错误或警告。错误行为可配置,请参阅下文。
链接到另一种语言版本
要链接到文档的另一种语言版本,请使用以下语法:
1
| \{\{\< relref path="document.md" lang="ja" \>\}\}
|
获取另一种输出格式
要链接到文档的另一种输出格式,请使用以下语法:
1
| \{\{\< relref path="document.md" outputFormat="rss" \>\}\}
|
标题ID
使用Markdown文档类型时,Hugo为页面上的每个标题生成元素ID。例如:
生成以下HTML:
1
| <h2 id="reference">Reference</h2>
|
在使用ref
或relref
简码时,通过将ID附加到路径来获取标题的永久链接:
1
2
| \{\{\< ref "document.md#reference" \>\}\}
\{\{\< relref "document.md#reference" \>\}\}
|
通过包含属性来生成自定义标题ID。例如:
1
2
| ## Reference A {#foo}
## Reference B {id="bar"}
|
生成以下HTML:
1
2
| <h2 id="foo">Reference A</h2>
<h2 id="bar">Reference B</h2>
|
如果同一标题在页面上出现多次,Hugo将生成唯一的元素ID。例如:
1
2
3
| ## Reference
## Reference
## Reference
|
生成以下HTML:
1
2
3
| <h2 id="reference">Reference</h2>
<h2 id="reference-1">Reference</h2>
<h2 id="reference-2">Reference</h2>
|
Ref 和 RelRef 配置
自 Hugo 0.45 开始,该行为可以在 config.toml
中进行配置:
refLinksErrorLevel (“ERROR”)
使用ref
或relref
解析页面链接时,如果链接无法解析,将使用此日志级别记录。有效值为ERROR
(默认)或WARNING
。任何ERROR
都将导致构建失败(exit -1
)。
refLinksNotFoundURL
在 ref
或 relref
中找不到页面引用时使用的 URL 占位符。则原样使用。
另请参阅
最后修改 May 22, 2023:
第一次提交 (9f24e27)