mirror/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2025-08-20 21:31:32 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge commit '5be51ac3db225d5df501ed1fa1499c41d97dbf65'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2025-04-10 13:04:51 +02:00
parent 208a0de6c3 5be51ac3db
commit 653f1c1d46
987 changed files with 12379 additions and 14083 deletions
Download Patch File Download Diff File Expand all files Collapse all files

73
docs/content/en/shortcodes/ref.md
View File

@@ -1,48 +1,61 @@
---
title: Ref
title: Ref shortcode
linkTitle: Ref
description: Insert a permalink to the given page reference using the ref shortcode.
categories: [shortcodes]
categories: []
keywords: []
menu:
docs:
parent: shortcodes
weight:
weight:
---
{{% note %}}
To override Hugo's embedded `ref` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
> [!note]
> To override Hugo's embedded `ref` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
[source code]: {{% eturl ref %}}
{{% /note %}}
> [!note]
> When working with the Markdown [content format], this shortcode has become largely redundant. Its functionality is now primarily handled by [link render hooks], specifically the embedded one provided by Hugo. This hook effectively addresses all the use cases previously covered by this shortcode.
{{% note %}}
When working with the Markdown [content format], this shortcode has become largely redundant. Its functionality is now primarily handled by [link render hooks], specifically the embedded one provided by Hugo. This hook effectively addresses all the use cases previously covered by this shortcode.
## Usage
[content format]: /content-management/formats/
[link render hooks]: /render-hooks/images/#default
{{% /note %}}
The `ref` shortcode accepts either a single positional argument (the path) or one or more named arguments, as listed below.
The `ref` shortcode returns the permalink of the given page reference.
## Arguments
Example usage:
{{% include "_common/ref-and-relref-options.md" %}}
```text
[Post 1]({{%/* ref "/posts/post-1" */%}})
[Post 1]({{%/* ref "/posts/post-1.md" */%}})
[Post 1]({{%/* ref "/posts/post-1#foo" */%}})
[Post 1]({{%/* ref "/posts/post-1.md#foo" */%}})
## Examples
The `ref` shortcode typically provides the destination for a Markdown link.
> [!note]
> Always use [Markdown notation] notation when calling this shortcode.
The following examples show the rendered output for a page on the English version of the site:
```md
[Link A]({{%/* ref "/books/book-1" */%}})
[Link B]({{%/* ref path="/books/book-1" */%}})
[Link C]({{%/* ref path="/books/book-1" lang="de" */%}})
[Link D]({{%/* ref path="/books/book-1" lang="de" outputFormat="json" */%}})
```
Rendered:
```html
<a href="https://example.org/posts/post-1/">Post 1</a>
<a href="https://example.org/posts/post-1/">Post 1</a>
<a href="https://example.org/posts/post-1/#foo">Post 1</a>
<a href="https://example.org/posts/post-1/#foo">Post 1</a>
<a href="https://example.org/en/books/book-1/">Link A</a>
<a href="https://example.org/en/books/book-1/">Link B</a>
<a href="https://example.org/de/books/book-1/">Link C</a>
<a href="https://example.org/de/books/book-1/index.json">Link D</a>
```
{{% note %}}
Always use the `{{%/* */%}}` notation when calling this shortcode.
{{% /note %}}
## Error handling
{{% include "_common/ref-and-relref-error-handling.md" %}}
[content format]: /content-management/formats/
[link render hooks]: /render-hooks/images/#default
[Markdown notation]: /content-management/shortcodes/#notation
[source code]: {{% eturl ref %}}