hugo-mod-link-hub

A Hugo module providing render hooks for links and images.

Features

Named Links

Centrally manage frequently used URLs in a single data file (data/link-hub.yaml). In Markdown, reference a link by its ID instead of its URL — if the URL changes, you only update it in one place.

Links support URL parameters: define a URL template with {1}, {2}, … placeholders and pass values directly in the Markdown.

Invalid link IDs are rendered as a visible error in the page and logged as a warning during the Hugo build.

Image rendering

Extends Hugo's default image render hook to correctly resolve images referenced with absolute paths (e.g. /media/image.jpg) as Hugo resources, and falls back to a baseURL-relative URL for static files from domain-based hosting setups.

Setup

Add the module to your hugo.yaml:

module:
  imports:
    - path: "gitlab.com/renzok/hugo-mod-link-hub"

Create data/link-hub.yaml in your project:

links:
  - id: "docs"
    url: "/docs"
  - id: "adr"
    url: "/decision-records/{1}"

Usage

Simple named link

[Getting Started](<$docs>)

Named link with parameters

[ADR with param](<$adr make-use-of-adr>)

The {1} placeholder in the URL is replaced with make-use-of-adr.

Link syntax

The link destination must be wrapped in angle brackets (<…>) because the $ prefix and any parameters contain characters that CommonMark does not allow in bare link destinations.

Named links within your site

Following https://gohugo.io/functions/urls/absurl/ or https://gohugo.io/functions/urls/abslangurl/

you should always provide the link relative to baseURL WITHOUT a leading slash /.

Local development

To preview the module in isolation, create a hugo.local.yaml (git-ignored) that adds a theme:

baseURL: 'http://localhost:1313/'
title: "link-hub-test"

module:
  imports:
    - path: "github.com/yihui/hugo-xmin"

Also create a content file using named links (e.g. content/test.md):

---
title: "Test"
date: 2026-01-01
---

[Named link](<$your-link-id>)

And then

 hugo server --config hugo.local.yaml --port 1414