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


#1

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?


#2

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/article_filename_here.md"  >}}

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.


#3

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?


#4

Are you using _index.md for section page content and front matter?

{{< relref "articles/_index.md" >}}


#5

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


#6

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…


#7

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.


#8

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).


#9

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.


#10

Any update on this issue ? how to relref to _index.md ?

@bep since nested section, how to achieve this ?


#11

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.

#12

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

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

  1. create a link to the section like that: {{< relref "mysection/index.md" >}}
  2. create an empty file mysection/index.md
  3. create the mysection/_index.md 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 _index.md 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.


#13

I had the same issue to relref to _index.md

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


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