sals.place

Backlinks on this site

You are viewing a note. This page may change often or disappear completely.

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:

  1. Iterate over each Markdown file in my site, scanning each file for internal links using regular expressions, and storing those links in a map.
  2. Build a second map from the first, this one with pages as keys and backlinks as the values.
  3. 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.


Backlinks

  1. Colophon