The ref and relref shortcodes link documents together, both of which are built-in Hugo shortcodes. These shortcodes are also used to provide links to headings inside of your content, whether across documents or within a document. The only difference between ref and relref is whether the resulting URL is absolute (http://1.com/about/) or relative (/about/), respectively.
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.
The documentname is the name of a document, including the format extension; this may be just the filename, or the relative path from the content/ directory. With a document content/blog/post.md, either format will produce the same result:
If you have the same filename used across multiple sections, you should only use the relative path format; otherwise, the behavior will be undefined. This is best illustrated with an example content directory:
When using Markdown document types, Hugo generates heading anchors automatically. The generated anchor for this section is hugo-heading-anchors. Because the heading anchors are generated automatically, Hugo takes some effort to ensure that heading anchors are unique both inside a document and across the entire site.
Ensuring heading uniqueness across the site is accomplished with a unique identifier for each document based on its path. Unless a document is renamed or moved between sections in the filesystem, the unique identifier for the document will not change: blog/post.md will always have a unique identifier of 81df004c333b392d34a49fd3a91ba720.
ref and relref were added so you can make these reference links without having to know the document’s unique identifier. (The links in document tables of contents are automatically up-to-date with this value.)