hugo

Fork of github.com/gohugoio/hugo with reverse pagination support

git clone git://git.shimmy1996.com/hugo.git

cross-references.md (3315B)

    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 The `ref` and `relref` shortcodes display the absolute and relative permalinks to a document, respectively.
   19 
   20 ## Use `ref` and `relref`
   21 
   22 ```go-html-template
   23 {{</* ref "document" */>}}
   24 {{</* ref "document#anchor" */>}}
   25 {{</* ref "document.md" */>}}
   26 {{</* ref "document.md#anchor" */>}}
   27 {{</* ref "#anchor" */>}}
   28 {{</* ref "/blog/my-post" */>}}
   29 {{</* ref "/blog/my-post.md" */>}}
   30 {{</* relref "document" */>}}
   31 {{</* relref "document.md" */>}}
   32 {{</* relref "#anchor" */>}}
   33 {{</* relref "/blog/my-post.md" */>}}
   34 ```
   35 
   36 To generate a hyperlink using `ref` or `relref` in markdown:
   37 
   38 ```md
   39 [About]({{</* ref "/page/about" */>}} "About Us")
   40 ```
   41 
   42 The `ref` and `relref` shortcodes require a single parameter: the path to a content document, with or without a file extension, with or without an anchor.
   43 
   44 **Paths without a leading `/` are first resolved relative to the current page, then to the remainder of the site.
   45 
   46 Hugo emits an error or warning if a document cannot be uniquely resolved. The error behavior is configurable; see below.
   47 
   48 ### Link to another language version
   49 
   50 To link to another language version of a document, use this syntax:
   51 
   52 ```go-html-template
   53 {{</* relref path="document.md" lang="ja" */>}}
   54 ```
   55 
   56 ### Get another Output Format
   57 
   58 To link to another Output Format of a document, use this syntax:
   59 
   60 ```go-html-template
   61 {{</* relref path="document.md" outputFormat="rss" */>}}
   62 ```
   63 
   64 ### Heading IDs
   65 
   66 When using Markdown document types, Hugo generates element IDs for every heading on a page. For example:
   67 
   68 ```md
   69 ## Reference
   70 ```
   71 
   72 produces this HTML:
   73 
   74 ```html
   75 <h2 id="reference">Reference</h2>
   76 ```
   77 
   78 Get the permalink to a heading by appending the ID to the path when using the `ref` or `relref` shortcodes:
   79 
   80 ```go-html-template
   81 {{</* ref "document.md#reference" */>}}
   82 {{</* relref "document.md#reference" */>}}
   83 ```
   84 
   85 Generate a custom heading ID by including an attribute. For example:
   86 
   87 ```md
   88 ## Reference A {#foo}
   89 ## Reference B {id="bar"}
   90 ```
   91 
   92 produces this HTML:
   93 
   94 ```html
   95 <h2 id="foo">Reference A</h2>
   96 <h2 id="bar">Reference B</h2>
   97 ```
   98 
   99 Hugo will generate unique element IDs if the same heading appears more than once on a page. For example:
  100 
  101 ```md
  102 ## Reference
  103 ## Reference
  104 ## Reference
  105 ```
  106 
  107 produces this HTML:
  108 
  109 ```html
  110 <h2 id="reference">Reference</h2>
  111 <h2 id="reference-1">Reference</h2>
  112 <h2 id="reference-2">Reference</h2>
  113 ```
  114 
  115 ## Ref and RelRef Configuration
  116 
  117 The behavior can, since Hugo 0.45, be configured in `config.toml`:
  118 
  119 refLinksErrorLevel ("ERROR") 
  120 : When using `ref` or `relref` to resolve page links and a link cannot resolved, it will be logged with this log level. Valid values are `ERROR` (default) or `WARNING`. Any `ERROR` will fail the build (`exit -1`).
  121 
  122 refLinksNotFoundURL
  123 : URL to be used as a placeholder when a page reference cannot be found in `ref` or `relref`. Is used as-is.
  124 
  125 
  126 [lists]: /templates/lists/
  127 [output formats]: /templates/output-formats/
  128 [shortcode]: /content-management/shortcodes/