github.com/rabbouni145/gg@v0.47.1/docs/content/en/content-management/cross-references.md (about)

     1  ---
     2  title: Links and Cross References
     3  description: Shortcodes for creating links to documents.
     4  date: 2017-02-01
     5  publishdate: 2017-02-01
     6  lastmod: 2017-03-31
     7  categories: [content management]
     8  keywords: ["cross references","references", "anchors", "urls"]
     9  menu:
    10    docs:
    11      parent: "content-management"
    12      weight: 100
    13  weight: 100	#rem
    14  aliases: [/extras/crossreferences/]
    15  toc: true
    16  ---
    17  
    18  
    19  The `ref` and `relref` shortcode resolves the absolute or relative permalink given a path to a document.
    20  
    21  ## Use `ref` and `relref`
    22  
    23  ```go-html-template
    24  {{</* ref "document.md" */>}}
    25  {{</* ref "#anchor" */>}}
    26  {{</* ref "document.md#anchor" */>}}
    27  {{</* ref "/blog/my-post" */>}}
    28  {{</* ref "/blog/my-post.md" */>}}
    29  {{</* relref "document.md" */>}}
    30  {{</* relref "#anchor" */>}}
    31  {{</* relref "document.md#anchor" */>}}
    32  ```
    33  
    34  The single parameter to `ref` is a string with a content `documentname` (e.g., `about.md`) with or without an appended in-document `anchor` (`#who`) without spaces. Hugo is flexible in how we search for documents, so the file suffix may be omitted.
    35  
    36  **Paths without a leading `/` will first  be tried resolved relative to the current page.**
    37  
    38  You will get an error if you document could not be uniquely resolved. The error behaviour can be configured, see below.
    39  
    40  ### Link to another language version
    41  
    42  Link to another language version of a document, you need to use this syntax:
    43  
    44  ```go-html-template
    45  {{</* relref path="document.md" lang="jp" */>}}
    46  ```
    47  
    48  ### Get another Output Format
    49  
    50  To link to a given Output Format of a document, you can use this syntax:
    51  
    52  ```go-html-template
    53  {{</* relref path="document.md" outputFormat="rss" */>}}
    54  ```
    55  
    56  ### Anchors
    57  
    58  When an `anchor` is provided by itself, the current page’s unique identifier will be appended; when an `anchor` is provided appended to `documentname`, the found page's unique identifier will be appended:
    59  
    60  ```go-html-template
    61  {{</* relref "#anchors" */>}} => #anchors:9decaf7
    62  ```
    63  
    64  The above examples render as follows for this very page as well as a reference to the "Content" heading in the Hugo docs features pageyoursite
    65  
    66  ```go-html-template
    67  {{</* relref "#who" */>}} => #who:9decaf7
    68  {{</* relref "/blog/post.md#who" */>}} => /blog/post/#who:badcafe
    69  ```
    70  
    71  More information about document unique identifiers and headings can be found [below]({{< ref "#hugo-heading-anchors" >}}).
    72  
    73  
    74  ## Ref and RelRef Configuration
    75  
    76  The behaviour can, since Hugo 0.45, be configured in `config.toml`:
    77  
    78  refLinksErrorLevel ("ERROR") 
    79  : When using `ref` or `relref` to resolve page links and a link cannot resolved, it will be logged with this logg level. Valid values are `ERROR` (default) or `WARNING`. Any `ERROR` will fail the build (`exit -1`).
    80  
    81  refLinksNotFoundURL
    82  : URL to be used as a placeholder when a page reference cannot be found in `ref` or `relref`. Is used as-is.
    83  
    84  
    85  [lists]: /templates/lists/
    86  [output formats]: /templates/output-formats/
    87  [shortcode]: /content-management/shortcodes/
    88  [bfext]: /content-management/formats/#blackfriday-extensions