hugo-mod-urlpreview

hugo-mod-urlpreview is a Hugo module that generates URL previews at build time. It provides a Hugo shortcode named linkpreview, which takes a URL and automatically embeds metadata such as title, description, and preview image.

This module is ideal for static sites, blogs, and documentation where link previews should be generated reliably without any client-side JavaScript.

Installation

1. Initialize Hugo Modules (if not already done)

hugo mod init github.com/USER/REPO

2. Add the module as a dependency

Add the import entry to your Hugo configuration.

config.toml

[module]
  [[module.imports]]
    path = "codeberg.org/dozrye/hugo-mod-urlpreview"

config.yaml

module:
  imports:
    - path: codeberg.org/dozrye/hugo-mod-urlpreview

Set API Key

The module requires an API key provided via environment variable. You can get an api key from https://urlpreview.com/ (there is a free tier, but be aware of rate limits).

Important: as with every application that relies on secret api keys, you should not expose these keys to the internet and/or commit them to your Git repo.

macOS / Linux

export HUGO_URLPREVIEW_API_KEY="your_api_key"

Windows (PowerShell)

setx HUGO_URLPREVIEW_API_KEY "your_api_key"

Note: Without this API key, the module cannot generate URL previews.

Using the Shortcode

The module provides the shortcode linkpreview.

Basic usage:

{{< linkpreview "https://example.com" >}}

The shortcode generates, at build time:

• Page title
• Description / meta description
• Preview image (if available)

Styling

example styling (might be integrated in this mod in the future):

$height: 250px;
$width: 600px;

@mixin link-preview-light(){
    @include link-preview-card($color-text-light, $color-muted-light, $color-background-light, $color-title-light);
}

@mixin link-preview-dark(){
    @include link-preview-card($color-text-dark, $color-muted-dark, $color-background-dark, $color-title-dark);
}

.colorscheme-dark{
    @include link-preview-dark;
}
.colorscheme-light{
    @include link-preview-light;
}

@media (prefers-color-scheme: light){
    @include link-preview-light;
}

@media (prefers-color-scheme: dark) {
    @include link-preview-dark;
}

For brevity, mixins and variables were omitted. See the full styling here.

How It Works

• During the hugo build, the module requests preview metadata via the API.
• Hugo fetches the data whenever it considers it necessary for the build.

Additional Notes

• Compatible with all recent Hugo versions that support Hugo Modules.
• If the API is unavailable or the API key is missing, the build will fail.

Author

This module is developed and maintained by @dozrye.

License

Apache 2.0 License