Struggling with URLs in Markdown

support
1

I’m having trouble getting links between files working (feeling very stupid today!)

For example:

content
  blog
    post-1.md
    post-2.md

In post-2.md I want to put a link to post-1.
e.g.

For more information, check out [post 1](post-1)

The problem I’m having is I can’t seem to get that to work in a nice way without it 404ing.

I have tried:
/post-1
/post-1.md
/post-1/
./post-1
etc.

In my config.yaml I had:

baseURL: /
relativeURLs: true
canonifyURLs: true

The baseURL needs to be / to play nice, as the built site gets pulled in to another site.

I have tried changing relativeURLs and canonifyURLs to false.

The only way I avoid 404s is to anticipate the output and have the following:

For more information, check out [post 1](../post-1)

This takes into account the fact that when built, everything ends up as an index.html in its own folder. But this is really nasty - I can probably remember and make sure to anticipate the build, but it’s likely to trip up other contributors to the project. There must be a more elegant way? It’s also tripping me up with adding images.

Edit to add: based off the docs here (https://gohugo.io/content-management/urls/#relative-urls) I would expect that with relativeURLs: true, putting /post-1/ would result in the the correct link. But instead I get a 404 to /blog/post-2/post-1

(am on 0.54.0)

Edit to add again: so I tried using the short code {{< ref “post-1” >}} and that worked. Are shortcodes the only way to do this? We’re losing the nice clean markdown (and low barrier to contribution) if writing with Hugo requires knowledge of Hugo-specific stuff.

1 Like
2

start reading here

3

Did you try:

/blog/post-1/

? If you never change any file and folder name it should work. If not read the doc-page that @ju52 linked. It should end up in something like {{< rev “/blog/post-1.md” >}}

The content folder is the “root” folder for your site (/), then add the folderstructure (post/) then the filename or other folders (post-1.md) -> /post/post-1.md.

4

the explicit link depend on your config file [Permalinks] - use this:

[blog one]({{< ref “/blog/post-1.md” >}})

5

Here’s the shortcode I use to link between asciidoctor files in my site:

{{ $page := .Site.GetPage (.Get 0) }}
{{ $title := default "" (.Get 1) }}
{{ if eq $page nil }}
    {{ errorf "Error in adoc_ref shortcode, at %s. File doesn't exist: %s" .Position (.Get 0) }}
{{ else if eq $title "Title" }}
    {{ $anchor := printf "<a href=\"%s\">%s</a>" $page.Permalink $page.Title -}}
    {{- $anchor | safeHTML -}}
{{ else if eq $title "linkTitle" }}
    {{ $anchor := printf "<a href=\"%s\">%s</a>" $page.Permalink $page.LinkTitle -}}
    {{- $anchor | safeHTML -}}
    {{/* No title parameter specified */}}
{{ else }}
    {{ $anchor := printf "<a href=\"%s\">%s</a>" $page.Permalink $page.Title -}}
    {{- $anchor | safeHTML -}}
{{ end }}

Also, writing with Hugo does require knowledge of Hugo. I don’t think there’s any way around that at the moment. Remember that Hugo isn’t just a vague and mysterious wrapper you put around your content. Your content has to have some awareness of Hugo, and Hugo has to have some awareness of your content.

In particular, you should consider using Hugo instead of your markup language for the following:

  • Links, especially between files in /content
  • Links to static files.
  • Escaped HTML
  • Tables, if your markup language doesn’t support them
  • Images (use the fig shortcode)
  • Code highlighting (I much prefer chroma)
  • Table of Contents (For an example, look at the docdock theme)

My site is at https://developers.signalfx.com.
Caveats:

  • Took a lot of time and effort
  • I’m a tech writer, but I’m also a former software engineer
  • An online tool like Stoplight or readme.io may suit you better, especially if you don’t have the time and resources to hammer at Hugo yourself.
  • The docdock theme did 50% of the work, and another 10-20% was contributed by the kind people in this discussion forum. The shortcode I presented is based on code someone gave me here.
6

Thanks for the replies folks. Looks like using the shortcode is the way to go here.

7

I was struggling with just a plain HTML link in my markkdown file. This is what solved it for me:

In config.toml file:
[markup]
[markup.goldmark]
[markup.goldmark.renderer]
hardWraps = true
unsafe = true
xHTML = true
plainIDAnchors = true
hrefTargetBlank = true
[permalinks]
dd = “/ss”

In the markdown file the link had to look like this:
<a class=intro-link href=https://gohugo.io>LINK TEST</a>
**notice no quotation marks around the href or class

Just thought I’d post that in case anyone was struggling with a plain HTML link in the markdown file. even though I had unsafe = true it never occurred to me to omit the quotation marks in the HTML to get it to work.