Implementing backlinks in a Hugo website

Include wiki-style links on your site

Photo by Pixabay from Pexels
Backlinks implemented on my site, gabrielle-earnshaw.com

What were my requirements?

I had the following requirements for implementing backlinks on my site.

  1. I wanted it to be simple enough that I could create the templates myself. I didn’t want to import a package or third-party code that would take time and effort for me to understand if I needed to make any changes.
  2. I didn’t want to be constrained by a particular Hugo theme. I wanted backlinking functionality to be independent of the look and feel of the site.

Implementation

There were three steps to implementing backlinks.

  1. Adding a linked to section to the single page template to display all articles in the linked to list.
  2. Adding backlinks in a referenced by section in the single page template. This loops through all articles in the site, listing every page that includes this page in its list of linked to articles.

1. Add a custom variable to the front matter

The first step was to add a custom variable called linkedArticles to the front matter to hold a list of articles linked to by this article.

linkedArticles: ["different-types-of-mobile-app", "Benefits-of-native-apps-over-web-apps"]
---
title: "Pros and Cons of Using Web Views Inside Native Apps"
date: 2021-04-19T19:47:02+01:00
draft: false
tags: ["Mobile", "Strategy"]
linkedArticles: ["different-types-of-mobile-app", "Benefits-of-native-apps-over-web-apps"]
---

A technique for adding functionality...

2. Add a ‘linked to’ section to the single page

The second step was to add a section to the bottom of the single page template, to list the linked articles for this page. I did this by looping over the list of linked articles added in the front matter content, and adding a link to each in my page.

{{ $parentPage := . }}

<h1>Linked to:</h1>
<ul>
{{ range .Params.linkedArticles }}
{{ $ref := ref $parentPage . }}
{{ $page := $parentPage.GetPage . }}

<li>
<a href="{{ $ref }}">{{ $page.Title }}</a>
</li>
{{ end }}

</ul>
  1. Use HTML to add a title and start a list.
  2. Use range to loop over the list of items in the linkedArticles variable.
  1. Use .GetPage to create a reference to the page object for the linked article, so we can access its title.
  2. Use HTML to add a list item containing a link to the page.
An example of the ‘linked to’ section

3. Add a ‘referenced by’ section to the single page

The third step was to add a section to the bottom of the single page to display the backlinks, i.e., the list of pages that have a link to this page. To achieve this, the template checks each page in the site in turn, looks at its linked articles, and adds links for all pages that have a link to this page.

{{ $parentPage := . }}
<h1>Referenced by:</h1>
<ul>
{{ range .Site.RegularPages }}
{{ $page := . }}
{{ range .Params.linkedArticles}}
{{ $linkedPage := $parentPage.GetPage .}}
{{ if eq $linkedPage $parentPage }}
<li>
<a href="{{ $page.Permalink }}">{{ $page.Title }}</a>
</li>
{{ end }}
{{ end }}
{{ end }}

</ul>
  1. Use HTML to add a title and start a list.
  2. Use range to loop over all the regular pages in the site.
  1. Use range to loop over all of that page’s linked articles.
  1. Use {{ if eq $linkedPage $parentPage }} to check if the linked article is actually the page that we’re currently rendering.
  2. If it is, use HTML to add a list item containing a ref to the page that links to us.
An example of the ‘referenced by’ section

Limitations

There are a couple of limitations with this implementation. The first is that, although the backlinks are added automatically, you have to manually add the links in the front matter. It would be nice if the links in the content was extracted automatically. However, for the volume of content I create, this isn’t a big overhead.

Summary

The implementation on my site has some styling applied, but is otherwise identical to what is listed here (at the time of publishing — no doubt it will evolve). The result is that I can add links to new articles, and the backlinks will automatically appear on existing articles with no intervention required. It was simple to add, and I’m pleased with the results. I hope you found this article useful.

Backlinks implemented on my site, gabrielle-earnshaw.com

Mobile app strategy and development. Principal Consultant at @InfinityWorks and creator of @Tasktimerappuk and Windsurf Caddy

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store