Possible to use regular markdown links to other .md files, rather than shortcodes?

support
1

Is it possible to use regular markdown links to other .md files in Hugo, or must one always use a shortcode?

To link to images and non-MD files, regular markdown links work, especially now with bundles as a feature. ex. ![image](/path/to/image)

But my understanding is that for other .md files, you need to use a shortcode:
[another article]({{< ref "path/to/file.md" >}}).

This shortcode is a little cumbersome and also not entirely futureproof. If stop using Hugo, these don’t render to regular HTML links as regular .md links do.

Is there are hack to get around this? Or am I misunderstanding something?

2

Why would you want to link to the .md files and not to their permalink?

Also Hugo 0.32+ supports symbolic links (if that’s what you mean).

3

It’s more about economy of writing the links and also so that they still work on my local machine. If I put the file path in the normal way, when I render the markdown, the links work locally. It’s more natural for me to just type in the .md file name. I suppose I could just make a keyboard snippet for shortcodes. I’ll read up on symbolic links in 0.32

4

As far as I can see, no, there is no way around it. Template code goes in templates, and the workaround to use that in markdown files is to use shortcodes.

I think that happens no matter what SSG you’re using / converting to.

In my opinion, use the permalink instead because, then at least you have a chance of converting directly, if you switch away from Hugo (but, why would you want to?! :slight_smile: )

5

The nice thing about having normal .md links in the files for me is that you can use the same markdown file on github and on hugo. In general, I’d like to write a bunch of ‘normal’ md files, then have hugo build them into my pages based on my theme and config, not pollute my markdown files with Hugo-only shortcodes (which look bad and don’t work when you try to click them on Github, for instance)

6

Is there a way to convert all of the links like

[Folding Example](/examples/folding.md)

so that they come out in the built site as

<a href="/examples/folding-example">Folding Example</a>

instead of

<a href="/examples/folding-example.md">Folding Example</a>

which 404s?

Ideally without adding a shortcode to the markdown file, since that will break the link when viewing the same page on Github.

7

I think I managed to get this working through a config change:

[permalinks]
posts = "/:sections/:slug.md"

This seems to work pretty well for my purposes!

8

Did you get this to work? I have the same requirement, and am surprised it’s so hard to accomplish with Hugo, whereas other SSGs do it by default.

9

It should be possible using Render Hook Templates if you’re using Goldmark (the default renderer since Hugo 0.60).

Paste this into layouts/_default/_markup/render-link.html:

{{- $url := .Destination -}}
{{- if ne (substr .Destination 0 1) "#" }}
    {{- $targetFile := .Destination | absURL -}}
    {{- range .Page.Site.Pages -}}
        {{- if eq $targetFile (.File.Path | absURL) -}}
            {{- $url = printf "%s%s" .RelPermalink (replaceRE "^[^#]*" "" $.Destination) -}}
        {{- end -}}
    {{- end -}}
{{- end -}}
<a href="{{ $url }}"{{ with .Title }} title="{{ . }}"{{ end }}>{{ $.Text }}</a>
{{- /* This tag removes whitespace at the end */ -}}

Basically, for every link written in any Markdown file it goes through all pages in the site and checks whether you’ve linked to its input file. If you did, it replaces the linked URL with the relative permalink of that page. Plus some regex trickery to preserve the fragment part (#this-bit) of replaced links.

Caveats:

  • I’ve only tested it in hugo serve.
  • It’s probably not very efficient for large sites with a lot of links and pages.
  • It uses Site.Pages, which according to the documentation “contains only the pages in the current language”, so if you’ve got a multilingual site you presumably can’t use this to link to pages in other languages.
  • I’m pretty new to Hugo so I’ve probably overlooked some other corner cases and there may be better ways to do this.
10

This should be more effective:

1 Like
11

This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.