23

I am new to HUGO (http://gohugo.io/) static site generator. I am running Hugo server locally accessible as localhost:1313. I am trying to link pages in two different sections. My "feature.md" file need a link to "grid_modules.md" and vice versa. Following is the directory structure for both files in hugo generated site.

~/mysite/content/about/feature.md

~/mysite/content/modules/grid_modules.md

What is the best way to link both pages together? What I am trying is the following

In feature.md:

"[grid_modules] (../modules/grid_modules)"

If I try to access this link, I get an error at "localhost:1313/about/modules/grid_modules" which I know is wrong location.

What I am missing in linking? Why I am not getting "localhost:1313/modules/grid_modules" instead.

Swier
  • 4,047
  • 3
  • 28
  • 52
Adeel
  • 343
  • 1
  • 2
  • 7
  • you can also checkout the documentation(https://gohugo.io/content-management/cross-references/), they give many examples on how to get it to work in different languages, not just markdown. – geneowak Sep 23 '21 at 17:12

4 Answers4

22

This answer builds upon the answer provided by bep. That answer is correct, but not very clear (as it took me many times reading it an trying different things before I found the solution).

As stated previously:

the URL of a page depends on your URL configuration (either through in https://gohugo.io/extras/permalinks/ or set directly as the URL on the individual page).

You can use the ref and relref tags within your markdown so that a link resolves to the correct URL.

For your example, this would look like one of the following (depending on whether you want an absolute or relative URL):

[grid_modules] ( {{< relref "modules/grid_modules" >}})
[grid_modules] ( {{< ref "modules/grid_modules" >}})
Clay
  • 381
  • 2
  • 6
  • Looks like this doesn't work with the reference format? I.e. `[my_link][id]` and `[id]: {{< relref "otherpage.md" >}} "my title text"` – BlueCacti Sep 02 '21 at 09:18
8

What the URL of a page depends on your URL configuration (either through in https://gohugo.io/extras/permalinks/ or set directly as the URL on the individual page).

And this is often not the same as the path on the file system.

Hugo have some helper functions that will help you, see ref and relref in this document:

https://gohugo.io/extras/crossreferences/

bep
  • 1,662
  • 15
  • 16
8

I ran into this same problem, and found the following simpler solution to work. When a url is specified in the form [text](/url/path) from a page under content/, the /url/path root is effectively content/ (or public/ in the rendered site). So, to link to "~/mysite/content/modules/grid_modules.md" from within "~/mysite/content/about/feature.md" you can simply write in "feature.md"

[grid_modules](/modules/grid_modules)
Mike M
  • 81
  • 1
  • 6
  • 2
    This is easy, but in case you change the destination page URL, you won't get an alert that the link is broken. While using ref or relref will trigger an alert. – Jeremie May 23 '22 at 14:02
2

For navigating the page to the different post in markdown, you can use the below one.

[About]({{< ref "/page/about" >}})

Make sure that

  1. Double quote("") the relative path
  2. Add slash / in front of the relative path
  3. The relative path starts from the root. For some hugo template, it might be /content/posts/xxx
oscarz
  • 1,184
  • 11
  • 19