Noob's mental model broken - wiki-like links?

support
1

I’ve never used hugo before, but I just tried a quick POC converting a dokuwiki, and I think I have a misunderstanding of some basic hugo concept.

Say I have a directory guide/ and in there I have guide1.md and guide2.md. I would expect to link (in guide1) to guide2 with something like this:
[See Guide Two](guide2)

Instead, that links to guide1/guide2. I end up using (/guide/guide2) to actually link to guide2.

I have read some hugo docs and tried ref and relref, but I think I’m missing something.

2

I don’t know how Dokuwiki links work, so cannot comment on how to get a similar behaviour in Hugo.

But from how I understand relative links in Hugo, you can indeed use the ref and relref shortcodes for that.

If you don’t use custom permalinks, but Hugo render permalinks based on the structure of your /content/ folder, that looks like:

{{< relref "guide/guide2.md"  >}} -> /guide/guide2/
{{< ref "guide/guide2.md" >}}  -> http://www.example.com/guide/guide2/

There’s more information on the links and cross references page, which from what I understand you already saw.

I’d be the first to say that relref and ref probably don’t help you much, since they still require considerable typing. It’s probably just as easy to create regular Markdown links like so: [see guide for more](/guide/guide2/).

I unfortunately don’t know of a way to get quicker/shorter links in Hugo for quick note-taking.

Hope this helps.

3

I guess, my real question is, why does a link to “guide2” in guide1.md link to “guide1/guide2” ? Given my wiki experience, that’s weird to me, but it seems to make perfect sense to hugo people, and I would like to understand why.

4

If I understand you correctly, then it’s caused by how you organised your content.

I guess based on your descriptions that you organised your files like so:

/content/
    /guide/
        /guide2.md

If you use standard permalinks (meaning, without changing the permalink setting), then the link to guide2.md would become /guide/guide2/.

If you structure your content differently and don’t put guide2.md in the /guide/ subdirectory like this:

/content/
    /guide1.md
    /guide2.md

Then the links to your two pages become /guide1/ and /guide2/ and then there’s no need to link to /guide/guide2/ anymore.

Of course you can use different ways to structure links in Hugo (see the previous link about permalinks). You can also override URLs. That way you can still keep guide2.md in its /guide/ folder, but then it will render at the URL you specify.

Hope this makes some sense.

5

Remember that you are not using a wiki system here.

What is happening is that you are telling the browser to link to the relative path: guide2. The browser interprets relative paths relative to the current page, which in this case is guide1 - thus creating a link to guide1/guide2. A link of /guide2 would link to https://example.com/guide2/, /example/guide2 would link to https://example.com/example/guide2/, etc. It’s how HTML normally works, which is why Hugo people aren’t surprised.

Use the ref and relref shortcodes for these links, and everything should work out.

1 Like
6

That’s how I would expect it to work, but it doesn’t for me. Sorry for not being clear.

I do have a content/guide directory that contains guide1 and guide2 markdown files. Sorry for not being clear.

If I put a relative link into guide1 to just guide2 (as in my OP), then the FULL path of that link is /guide/guide1/guide2. It’s the guide1 part that hugo adds that confuses me (and makes the link a 404). If link to /guide/guide2, it works. Adding the current page in to the relative link is what I can’t figure out a good reason for (but I suspect there is).

7

That is how relative URLs work. A relative URL means relative to the linking document.

This is important, because “wikilinks” ([[link]]) doesn’t work this way. Most wikae have namespaces, and a different meaning of relative.

This isn’t an issue with your site or anything, just a different meaning of that term, relative.

I put together a few examples of how links work in Markdown and Hugo. You can see the links for each example, but you should check the source of the page:

<ul>
<li><code>[test](test)</code> = <a href="test">test</a></li>
<li><code>[test](/test)</code> = <a href="/test">test</a></li>
<li><code>[test](../test)</code> = <a href="../test">test</a></li>
<li><code>[test](https://interi.org/test)</code> = <a href="https://interi.org/test">test</a></li>
</ul>

I hope this helps your mental model. :slight_smile:

I couldn’t find a decent canonical resource that wasn’t an RFC or spec, but search around for relative and absolute URLs.

My personal advice is to not use relative links in content; as it get aggregated around (copied, RSS, indexed, etc), not all systems are smart enough to fill in the full path. I use absolute URLs for everything.

Relative URLs are okay for other use cases, such as if the content is used offline or propagated to lots of different domains.

8

This is true, but as a little sidenote: if you set canonifyURLs in the configuration file to true, Hugo automatically turns relative URLs like /guides/intro/ into www.example.com/guides/intro/ based on the base URL setting.

That way you can still write relative URLs in the content (which is much easier in my opinion, and more ‘wiki style’) but still have the website render with absolute URLs.

See here for the configuration variables. (Not that you need to read that link Maiki but I mention it here for Manithree in case he’s/she’s wondering what I’m talking about.)

1 Like
9

Ah. The light bulb went on. Hugo generates a directory for every markdown file. That’s what makes hugo relative urls different than relative urls in plain html or wikis.

I had noticed the directory structure in the public/ directory, but just hadn’t put that together.

Thanks all.