How to link to section pages with ref/relref shortcodes?


Inside an article markdown i would like to link into a section page using the ref/relref shortcodes. However when I do this, e.g.

{{< ref "articles" >}}

I’m getting No page found with path or logical name "articles".. I’m probably missing something super-simple here, but I cannot make it work for all the tea in china. So how would I create a link to a section inside markdown?


Could you kindly show the shortcode?

EDIT: upon re reading I realize I misundrestood. I thought you customized the shortcode.

For the default shortcode in Hugo, you must pass the relative path to the markdown file .md

such as

{{<  ref "section_name_here/"  >}}

The reason why it says “No page found with path or logical name “articles”” is because this file path “articles” doesn’t exist. I hope that helps.


Well, i understand why i get that message, the question is how do you link to sections from markdown when the shortcode is not working for that?


Are you using for section page content and front matter?

{{< relref "articles/" >}}


Using articles/ produces the same message (even though the file actually exists).


Do you happen to have relativeURLs set to true in your configuration? I ask because I wonder if it’s just easier to then write [my link to the articles](/articles) and let Hugo create the relative path for you…


Ok so it seems that one cannot use relref / ref for sections. I used a manual relative link now as you suggested. Thank you for your help.


That’s why I linked the markdown syntax document. What you are trying to do is easily accomplished using markdown (no need for a shortcode) for sections.

Simply [Link Title Here](/SECTION_NAME_HERE).


I see. However if I choose to switch the URL-scheme to ugly urls, I will have to change all “manual” markdown links created like this. This is why I wanted to use the shortcode as this transparently handles URL generation according to the site settings. It’s not much of a big deal though, so I’ll go with the markdown solution for now.


Any update on this issue ? how to relref to ?

@bep since nested section, how to achieve this ?


Not sure how this is related to nested sections, but this is the status:

  • ref/relref is (still) about linking to regular content pages (i.e. not home page, sections etc.)
  • you can, however, use .Site.GetPage to get to whatever you want, even regular pages, and I guess you could write a clever shortcode to handle this. This should maybe be baked into the built-in ref/relref shortcodes, but someone other than me will have to fix that.


I have the same problem to create a link to a section with relref and

The only disgusting solution I found for that to work is:

  1. create a link to the section like that: {{< relref "mysection/" >}}
  2. create an empty file mysection/
  3. create the mysection/ file with the content of my section homepage

This way I can create a link to the section, and while going on it, it renders the content of file.

I need to work like this because I’m migrating a wiki (dokuwiki) to Hugo. So each directory is a kind of subsection of the initial wiki. But Hugo considers them as section.


I had the same issue to relref to

I created a relref shortcode to made it possible with @bep suggestion : see here :

Using relref with files
Crossreferences to index-pages in section not working