Add Backlinks to Hugo

Oct 01, 2024

Hey,

I have been reading and growing interest (no pun intended) on the digital gardening concept.

One of the key ideas I liked is that content is heavily interconnected. It makes sense, right? We are on the internet after all. Hyperlinks are great 🔥!

What follows is a quick overview on how I added backlinks to my Hugo site.

What are backlinks?

Basically it is a link to where some page is being linked from.

Imagine you create a link from page A to page B. Then you get a backlink (in page B) pointing to A. Think of it as a backreference.

The reasoning behind is that if you find an article you like maybe you also like other articles that are linking to it.

Implementation using partials.

⚠️ Disclaimer: I am no expert at all on Hugo. So this is my humble approach. If you have any suggestion or comment about the implementation let me know by email or any social networks at the bottom.

Partials, as we saw previously, are a good way to extend your hugo site.

They provide a nice and tidy mechanism to add custom code. You write code in separate files and then include them in the appropriate place in your templates.

The first step is deciding where we want to display the backlinks.

In my case it was easy. Previously I already modified my single.html file (to add the like button).

And I think that right below the like button would look nice.

Copy layout file from your theme.

As I said I didn’t have to do this, since I already had my single.html under layouts/_default/single.html that I copied from my theme’s folder with something like:

$ cp themes/manis/layouts/_default/single.html layouts/_default/single.html

Modify layout.

Hopefully you already know where you want to put your backlins (don’t you?)

Go and add the following line to include the partial:

{{ partial "backlinks" . }}

☝️ The dot “.” is important. This is the way we define the scope for the partial. If you don’t understand what is this don’t worry. Just remember to add it.

In my case this is how the whole layouts/_default/single.html looks like after adding the partial:

{{ partial "header" . }}
<article>
	<header>{{ partial "title" . }}</header>
	{{ .Content }}
	{{ partial "likes" }}
</article>
{{ partial "backlinks" . }}
<nav class="no-print post-nav">
{{ if .PrevInSection }}
	<a class="prev-post" href="{{ .PrevInSection.Permalink }}">
		<img class="icon-text" src="/img/prev.svg"/>
		{{- .PrevInSection.Title -}}
	</a>
{{ end }}
{{ if .NextInSection }}
	<a class="next-post" href="{{ .NextInSection.Permalink }}">
		{{- .NextInSection.Title -}}
		<img class="icon-text" src="/img/next.svg"/>
	</a>
{{ end }}
</nav>
{{ partial "footer" . }}

Create backlinks partial

Okay, let’s create the ‘backlinks’ partial.

Create the file layouts/partials/backlinks.html.

With the following contents:

{{ $permalinkurl := urls.Parse $.Page.Permalink }}
{{ $relpermalink := $permalinkurl.Path }}
{{ $pages := slice }}
{{- range .Site.RegularPages -}}
    {{- if strings.Contains .Content $relpermalink -}}
        {{ $pages = $pages | append . }}
    {{- end -}}
{{- end -}}
{{ with $pages }}
<link rel="stylesheet" type="text/css" href="/css/backlinks.css">
<section class="backlinks">
    <h1>Backlinks</h1>
    <div class="backlink-items">
    {{- range $pages -}}
        {{- if strings.Contains .Content $relpermalink -}}
        <div class="backlink-item"><a href="{{ .Permalink }}">{{ .Name }}</a></div>
        {{- end -}}
    {{- end -}}
    </div>
</section>
{{ end }}

I will admit that the above code took me MUCH longer to write than I would like to admit.

But, hey!, that’s why I decided to write this post :)

Let me go over the interesting part line by line:

$permalinkurl := urls.Parse $.Page.Permalink: This uses the urls.Parse function to parse the url that we get from the parent scope (remember?).
{{ $relpermalink := $permalinkurl.Path }}: We extract the path (the most interesting part to us).
{{ $pages := slice }}: We create an empty array (weird way right?)
{{- range .Site.RegularPages -}}: Iterate over ALL the pages in the site.
{{- if strings.Contains .Content $relpermalink -}}: Check if the content of the pages contain the path that we extracted from the current article.
{{ $pages = $pages | append . }}: Collect all the pages (that contain a link to the current page) in an array.

The rest of the file is just adding a link to the CSS and some basic HTML.

I added the CSS in a separate file static/css/likes.css. This is the content:

.likes {
    display: flex;
    justify-content: center;
    margin: 25px 0px;
}
.likes__button {
    display: flex;
    border-radius: 100%;
    border: 2px solid #ff8181;
    height: 50px;
    align-items: center;
    justify-content: center;
    padding: 5px;
    min-width: 50px;
}
.likes__button:hover {
    background-color: #ff8181;
    cursor: pointer;
}
.likes__emoji {
    font-size: 25px;
}

Additional Notes

This article is way longer than I anticipated. But there some quick notes I don’t want to skip.

Syntax in Hugo templates is weird.
Managing arrays is just terrible – we need an empty slice function to create them.
The logic above is not performant at all. But since this is my personal blog and I only have a handful of articles I think we are good.
Scopes (or context) is something really important to understand in Hugo. Documentation here.

Done 🎉

This is how it looks in my blog :)

image_2023-05-30-23-36-12 Backlinks section appears at the bottom of articles.

Don’t focus too much on the design, because I will probably iterate over it.

The important thing is: we have now backlinks on every linked article!

I hope you enjoyed the article and maybe even learn a little 💪.

Let me know by smashing the 👍 button below or reach out to me by email.

🧠 THOUGHT: I think I have made multiple posts already about Hugo, which is nice. But I want to add a bit of variety to the blog. So I think this will be the last in a while.

👍