Harry Cresswell

Adding external articles to your Hugo list page

Lately I’ve been publishing articles both here on my personal site and on Medium. It seems to be fairly common practice these days. Perhaps you’re doing something similar?

In order to stay organised — as I publish on various sites — it seems logic to try and keep track of everything I’m writing in one place, that means here on my personal site.

To do this I came up with a super simple solution which extends the typical Hugo List template to include posts from external sources (in this case Medium). You’ll find this useful if like me you publish articles on multiple sites and want to link to all of them from one posts page on your Hugo site, without having to duplicate articles.

For a quick demo of this in action click on a few of my articles and you’ll notice some link to internal pages on this site and some link to external sources.


All that’s needed to add external post links to your post list page, is one line of front matter, and some logic in the form of an If statement which uses the isset function.

Step 1: Create new post with specific front matter

First you’ll need to create a new post for your external article.

In my case I do this by moving into the site folder within my Hugo site. From the command line: cd site, then hugo new articles/external-article-name.md. If you haven’t changed the name of your content type then you will use hugo new posts/external-article-name.md.

You should now have a new article in site > content > articles with basic front matter included.

Inside the front matter of your new post, include a new param for your external article. I called mine affiliatelink, but you could use something like externallink if you prefer. Add the URL of your external article as the value.

Your posts should now look something like this:

title: "Sketch Libraries and primitives to build buttons"
date: 2018-01-26T21:29:52+01:00
affiliatelink: "https://medium.com/@harrycresswell/using-sketch-libraries-and-primitives-to-build-an-even-better-system-of-buttons-ecc8f25486ac"

This is all you need to do in the post.

Step 2: Extending the List page template

In order to get external articles showing on your list page, jump back into your list.html layout. In most cases you’ll find this in layouts > _default.

If you haven’t made any major changes your list page should look something like this:

{{ define "main" }}
    {{ range .Data.Pages }}
        <h3><a href="{{ .Permalink }}">{{ .Title }}</a></h3>
    {{ end }}
{{ end }}

Pretty simple stuff. All we’re doing here is looping through our posts and printing out the post title. In this case clicking the title will take you do to the single post url. This should look familiar.

Now we need to extend this to include links to our external articles within the same loop:

{{ define "main" }}
    {{ range .Data.Pages }}
            <!-- If external link exists in post matter -->
            {{ if isset .Params "affiliatelink" }}
                <a href="{{ .Params.affiliatelink }}" target="_blank">{{ .Title }}</a><span>&#8599;</span>
            <!-- Else show internal post page -->
                <a href="{{ .Permalink }}">{{ .Title }}</a>
            {{ end }}
    {{ end }}
{{ end }}

So what’s going on here?

First Hugo looks for affiliatelink in the front matter of our post. If the parameter exists, isset returns true and replaces our usual permalink with the URL value from our post front matter. If a value for affiliatelink doesn’t exist, our list behaves as normal. We handle this with an else statement.

Wrapping up

Hopefully you’ve now implemented a simple bit of logic which serves up both external and internal links on your website.

On a final note, if you want to differentiate between the different post types try using the icon and wrap in a positioned after your title. I also added a target='_blank' to the a tag. It’s not essential but it’s a quick and easy way to show your readers that the post is from an external source and the link will open in a new window

I hope you’ve found this helpful. Any questions leave me a message or shoot me a tweet!

Weekly Brain—tactics

Brain—tactics contains a bunch of useful tools, articles and tips. No spam ever, just good honest content. Unsubscribe with one click, anytime.