Clarification on difference between references, links, and paths. Desperately needed.

[anoduck]

Spent about two hours going around in circles like a cat chasing his tail, trying to get a basic internal link to be accepted. The docs state from now on internal links need to be written as references, because Hinode now uses a renderer to process links. So, what is a reference, even more mysterious, what is a relative reference, and why does the filename or path not work?

From the review of the docs, it appeared as if references were the id attributes assigned to a heading. Ex. <h2 id="some-phrase">Some Phrase</h2> So in this example, if I wanted to create a link to the page containing the heading, I would use [Some Phrase]({{%ref: 'some-phrase' %}})? Just stating the obvious, this would require every page to have at least one heading.

If every page on the site had a different name, then what would the point of relative references be?

[anoduck]

Ok, ok, ok... So all is answered in the land of me.

---

Reviewed the Hugo Docs once again, and it combined with sleep, gave more clarity to the above posed question.

What is the difference between a ref and a relref?

After reading the documentation, it appears there is little to no distinction between ref and relref, because ref itself can be used to create both reference links and relative reference links. Where relref does not appear to serve any unique function other than creating solely relative reference links.

From the review of the docs, it appeared as if references were the id attributes assigned to a heading. Ex. <h2 id="some-phrase">Some Phrase</h2> So in this example, if I wanted to create a link to the page containing the heading, I would use [Some Phrase]({{%ref: 'some-phrase' %}})?

Not necessarily so. A reference can be a path to a content file with or without its extension, or a path to a content file with "id" attribute (referred to as an anchor). If the path is open, i.e. some/path.md then the reference is relative, if it is closed i.e. /some/path.md then the reference is relative to the site root (global). A file does not require an included heading are not required, but do generate anchors for references, and if a heading contains spaces, these spaces are replaced with hyphens -.

So, for everyone's reading pleasure, here is a convenient table of examples:

Reference	File Path	Webpath	Type	Shortcode Label	Context
{{% ref "page1" %}}	/content/docs/page1.md	/docs/page1/	filename - extension	"ref"	/docs/
{{% ref "page2.md" %}}	/content/docs/page2.md	/docs/page2/	filename w extension	"ref"	/docs/
{{% ref "/blog/post1.md" %}}	/content/blog/post1.md	/blog/post1/	path	"ref"	/ or "web root"
{{% ref "/docs/page3/#heading-anchor" %}}	/content/docs/page3.md	docs/page3/#heading-anchor	anchor	"ref"	/ or "web root"
{{% ref "post2/#heading-anchor" %}}	/content/blog/post2.md	blog/post2/#heading-anchor	anchor	"ref"	/blog/

There are many more examples that could be provided, but these examples do overview the varieties
described above.

---

ISSUE: Hugo was unable to find pages associated with reference links.

Solution:

When a content directory possesses a index.md rather than a _index.md, Hugo treats THE ENTIRE DIRECTORY as headless, thus does not render the directory's content into pages in the normal manner. Headless content is used when it is referenced and embedded in other files.

Thus in summary, Hugo was unable to find the page associated with references, because it was being asked to associate reference links with headless content, thus there was no rendered file to associate the reference link with.