Relref not working in the context of Markdown link

[BonfireAtNight]

Hello people,

first of all, I hope the following issue was not discussed (many times) before. To my surprise I couldn’t find any threads on the topic.

As the Docs explain, relref can be used to create links. I have two files in one directory, _index.md and voraussetzungen.md. I want to link from the former to the latter, by using [Test]({{< relref "voraussetzungen" >}}).
What I expected: <a href="RELATIVEPATH">Test</a>
What actually happened: <a><span>Test</span></a>

The individual components do seem to work:
{{< relref "voraussetzungen" >}} → /de/inhalte/fedora/virtuelle-maschinen/voraussetzungen/
[Test](/de/inhalte/fedora/virtuelle-maschinen/voraussetzungen/) → <a href="RELATIVEPATH">Test</a>

Similarly, using relref in the context of HTML works fine, too:
<a href="{{< relref "voraussetzungen" >}}">Test</a> → <a href="RELATIVEPATH">Test</a>

I suspect the (one) argument is not properly passed to the relref shortcode in the given (Markdown) context. But I don’t see why.

Additional information:
I’m not using a theme.
Environment:

❯ hugo env
hugo v0.121.2+extended linux/amd64 BuildDate=2024-02-07T00:00:00+00:00 VendorInfo=Fedora:0.121.2-1.fc40
GOOS="linux"
GOARCH="amd64"
GOVERSION="go1.22rc2"
github.com/sass/libsass="3.6.5"
github.com/webmproject/libwebp="v1.3.2

Configuration:

baseURL = 'http://localhost:1313/'
languageCode = 'de-DE'

defaultContentLanguage = 'de'
defaultContentLanguageInSubdir = true
[languages]
  [languages.de]
    disabled = false
    weight = 1
    languageName = "Deutsch"
    contentDir = "content/de"
    languageCode = 'de-DE'
    languageDirection = 'ltr'

  [languages.en]
    disabled = false
    weight = 2
    languageName = "English"
    contentDir = "content/en"
    languageCode = 'en-US'
    languageDirection = 'ltr'

[taxonomies]
  tag = "tags"

[frontmatter]
date = ["date", "publishDate", "lastmod"]
lastmod = ["lastmod"]

[markup.goldmark]
  [markup.goldmark.renderer]
    unsafe = true

[markup.highlight]
  style = "onedark"

Does anyone have an idea what might be going on? Big thanks in advance!

Summary: Below you’ll find the solution. I used the different shortcode notation and the link works fine.

There was some confusion as to what directory structure to use, at least on my part. As far as I can tell, the initial structure that represents a Branch Bundle should be fine.

[chrillek]

@BonfireAtNight

I have two files in one directory, _index.md and voraussetzungen.md.

That sounds like “I have a brunch bundle with a content file.” Which is not what you should have:

Page bundles

Then your configuration contains a broken baseURL (which is probably not related to your experienced problem, but you should fix it anyway. With that setting, your site will not work correctly when you move the content to the final destination).

In any case: Posting a link to your repository will get you useful answers a lot quicker than posting arbitrary snippets of code.

[BonfireAtNight]

Thanks for your answer! I’ve created a demo repo. This is the file I was talking about.

I read about this difference between Leaf Bundles and Branch Bundles. In regard to the two content example files, the Docs say: “These are resources of resource type page, accessible via the Resources method on the Page object. Hugo will not render these as individual pages.”
However, I did want to render the associated pages individually as part of a series. That is, you would first get to _index.md and follow a link to voraussetzungen.md. Do these two need their own directories with index.md files?

I understand that the baseURL wouldn’t work in production, but what would you do locally? Do I just put in the proper domain (the one to be used in the future) and hugo server will know what to do anyway?

[chrillek]

If you change the structure of Inhalte to this

inhalte
├── _index.md
├── fedora
│   ├── _index.md
│   └── virtuelle-maschinen
│       ├── _index.md
│       ├── theorie
│       │   └── index.md
│       └── voraussetzungen
│           └── index.md
├── laravel-concepts
│   └── mvc.md
└── nvim
    └── verzeichnisstruktur.md

the relref seem to work ok.

@BonfireAtNight

I understand that the baseURL wouldn’t work in production, but what would you do locally?

You don’t do anything locally. You set your baseURL to https://mydomain.de, and when you run hugo server, hugo takes care of everything. Similarly if you run hugo.

[jmooring]

@BonfireAtNight

Does anyone have an idea what might be going on?

When using a link render hook you must call the ref/relref shortcodes using the {{% %}} notation:

[Test]({{% relref "voraussetzungen.md" %}})

[jmooring]

@chrillek

@BonfireAtNight

I have two files in one directory, _index.md and voraussetzungen.md.

That sounds like “I have a brunch bundle with a content file.” Which is not what you should have

There’s nothing wrong with the existing structure.

@BonfireAtNight

Do these two need their own directories with index.md files?

There’s nothing wrong with the existing structure.

[BonfireAtNight]

To be honest, changing the directory structure didn’t help with the issue. But I do see why I would want to do this anyway, since… well, they are Leaf Bundles. Thanks for the clarifications!

Edit: Actually, this example is structured exactly as what I had in the beginning. I think I’ll return to that and just use the {{% shortcode %}} notation.

[BonfireAtNight]

This actually worked, thanks!

To be honest, I’m not quite sure why. This is what the FAQ says:
Use the {{% shortcode %}} notation if the shortcode template, or the content between the opening and closing shortcode tags, contains Markdown. Otherwise use the
{{< shortcode >}} notation.

The shortcode is between Markdown, but technically it doesn’t contain Markdown, right?

[jmooring]

There’s a long story behind this, which I’ve written about on many occasions. For example:
https://discourse.gohugo.io/t/links-rendering-issue/50200/4?u=jmooring

[BonfireAtNight]

Thanks for the clarification, I’ll look into this!

[chrillek]

The documentation says that a branch bundle (which is identified by containing _index.md) can contain any resource types but a page. I’d have thought that voraussetzungen.md alongside _index.md is exactly that: a page inside a branch bundle. Where am I going wrong?

[jmooring]

A content file (e.g., foo.md, foo.html, foo.adoc, foo.pdoc, foo.org, foo.rst) in a branch bundle is not a page resource… it’s a page.

[chrillek]

Thanks. I still find it confusing, though. The documentation also says

In a branch bundle, these files are only accessible as content pages.

and previously

Files with resource type page include content written in Markdown…

So, an MD file is of “resource type” page, always. But in a branch bundle, it is a “content page” (also? or does it become one?) . Or maybe it “is” not a content page, but can be accessed as such?

And the glossary tells me that a “page resource” is “a file within a page bundle”. Which could be understood to mean that all files in a page bundle are page resources – including an MD file in a branch bundle.

Similarly, the glossary says (in the "resource type entry) that

Content files such as Markdown, HTML, AsciiDoc, Pandoc, reStructuredText, and Emacs Org Mode have resource type page.

I’m not a native English speaker, which might be at the root of my confusion here.

[jmooring]

@chrillek

So, an MD file is of “resource type” page, always.

No. A markdown file named something other than index.md is only a page resource when it’s within a leaf bundle, which is any directory containing an index.md file.