Backlinks on this site
My pages have Obsidian-esque backlinks.
Before a build, a Python script scans my Markdown files and writes the link data to data/backlinks.json, creating a
Hugo data source.
Then, a Hugo template reads the data and generates the backlinks HTML on each page.
A dear reader and fellow blogger asked for some more details on this, so here you go!
The script logic:
- Iterate over each Markdown file in my site, scanning each file for internal links using regular expressions, and storing those links in a map.
- Build a second map from the first, this one with pages as keys and backlinks as the values.
- Dump that second map to
data/backlinks.json.
Here’s the pertinent Python code at the moment:
def collect_backlinks(content_dir: Path) -> dict[str, list[str]]:
page_links: dict[str, list[str]] = {}
for permalink, body in iter_markdown_pages(content_dir):
targets = [ensure_trailing_slash(match.group(1)) for match in INTERNAL_LINK_RE.finditer(body)]
for block in MENU_BLOCK_RE.finditer(body):
for line in block.group(1).splitlines():
href, _, _ = line.partition("|")
target = href.strip()
if target.startswith("/"):
target, _, _ = target.partition("#")
targets.append(ensure_trailing_slash(target))
page_links[permalink] = targets
backlinks: dict[str, set[str]] = {}
for source_url, targets in page_links.items():
for target_url in targets:
if target_url == source_url or target_url not in page_links:
continue
backlinks.setdefault(target_url, set()).add(source_url)
return {key: sorted(sources) for key, sources in sorted(backlinks.items())}
It’s plenty fast:
> time scripts/backlinks
Mapped backlinks for 138 pages -> data/backlinks.json
________________________________________________________
Executed in 114.36 millis fish external
usr time 98.24 millis 897.00 micros 97.34 millis
sys time 16.22 millis 0.00 micros 16.22 millis
The JSON file looks like so:
{
"/blog/11ty-to-hugo/": [
"/blog/find-your-drafts-with-ripgrep/",
"/blog/rss-oopsie-powrss-props/",
"/history/"
],
"/blog/24-hours-with-emacs/": [
"/blog/sorry-about-that-emacs-post/",
"/blog/text-editor-objectivity/",
"/blog/uses-update-vscode-todoist/",
"/notes/text-editors/"
],
// ...
}
And here’s the Hugo template.
Note there’s some extra complexity because I use date frontmatter for my blog dates but modification times for my notes dates.
{{- if not hugo.Data.backlinks }}
{{- errorf "backlinks.html: data/backlinks.json is missing or empty" }}
{{- end }}
{{- if ne .Params.backlinks false }}
{{- $key := .RelPermalink }}
{{- $backlinks := index hugo.Data.backlinks $key }}
{{- with $backlinks }}
{{- $validPages := slice }}
{{- range . }}
{{- with site.GetPage . }}
{{- if ne .RelPermalink $key }}
{{- $date := or .PublishDate .Lastmod }}
{{- if eq .Type "notes" }}
{{- $date = or .Lastmod .PublishDate }}
{{- end }}
{{- $validPages = $validPages | append (dict "page" . "sortDate" ($date.UTC | time.Format "2006-01-02T15:04:05Z")) }}
{{- end }}
{{- end }}
{{- end }}
{{- with $validPages }}
<h2>Backlinks</h2>
<ol class="postlist">
{{- range sort . "sortDate" "desc" }}
{{ partial "pagelistitem.html" .page }}
{{- end }}
</ol>
{{- end }}
{{- end }}
{{- end }}
Because the script is fast and Hugo can look up backlinks in a map keyed by page (rather than having to any lengthy scans), all of this has minimal impact on build times. My build pipeline runs in about 0.6 seconds.