Hugo Artifacts

Overview

Hugo Artifacts is a public, MIT-licensed monorepo of reusable Hugo modules — small, independently versioned components that drop into any Hugo site. The full source is on GitHub, and every artifact lives in its own subdirectory with an independent go.mod, so a site can import exactly the one piece it needs and pin it on its own release cadence.

The collection is built around a single, deliberate principle: an artifact ships structure, data, and behavior — never design decisions. Each shortcode emits semantic BEM markup, exposes its objective values as data-* attributes, and includes zero CSS — no stylesheet, no hardcoded colors, no dark-mode rule. The consuming site owns all visual presentation. That is what lets one component live on many unrelated sites and look at home on every one of them.

The Problem

Across the sites I build, I kept rewriting the same handful of components — a GitHub repository card, a privacy-respecting video embed, an admonition box — and each rewrite was a small compromise. The reusable Hugo modules I could find on the shelf were the opposite of reusable in the way that mattered: they shipped their own opinionated CSS, their own colors, sometimes their own baked-in dark-mode rule. Dropping one into a site with its own design system meant fighting it — overriding styles, untangling specificity wars, or forking the module outright just to restyle it. A component that imposes a look is not really reusable; it is a theme fragment wearing a module's clothes.

What I actually wanted was a component that crosses the styling boundary with data, not styles — that hands my site the facts (this is a danger callout, this video is id=abc, this repo has this many stars) and the semantic hooks to render them, and then gets out of the way so my own tokens and dark-mode rules flow straight through.

The Solution

Hugo Artifacts is that idea, applied consistently across a growing set of modules. Two kinds of artifact live in the monorepo.

Shortcodes — style-agnostic content components, each with its own README.md, installation path, and parameter surface:

• github-repo renders a GitHub repository reference in one of five display variants — inline, card, stats, lang, and hero — with live API-driven metadata, header-aware retries, and graceful degradation to a compact chip when the API is unreachable or rate-limited.
• hf-space does the same for a Hugging Face Space, with five variants of its own and live Hub metadata (emoji, SDK, hardware, likes, running status, gradient colors). It is the sibling of github-repo and follows the identical contract.
• youtube-embed is a privacy-first YouTube facade: it renders only a same-origin, build-time-fetched poster plus a real play button, and injects the youtube-nocookie.com player only on click, so the page makes zero third-party contact before the visitor opts in.
• callout is a universal admonition box — fifteen first-class types, true-synonym aliases, arbitrary custom types, native <details> collapsibility, opt-in ARIA, and overridable icons. It also ships a blockquote render hook so GitHub-style > [!NOTE] alerts render as the same markup. It supersedes the older, opinionated notice shortcode.

Modules — larger, consumer-facing capabilities. The flagship is pwa, a production-grade Progressive Web App module: a templated web app manifest, a modern RealFaviconGenerator icon set, a Workbox-powered service worker, an install prompt, and push-subscription wiring. It composes from two vendor-mount companions (workbox and idb) that expose their upstream JavaScript sources as Hugo assets for js.Build — a clean resolution recipe that needs no upstream replacement or vendoring.

The shared contract is what holds it all together. The one visual thing every shortcode does ship — its icons — renders as inline SVG using currentColor and 1em sizing, so even the icons inherit the consumer's text color and font size and stay fully restyleable. The payoff is that you can build a design of any complexity on top of these artifacts without fighting styles they impose, because they impose none.

Why a Monorepo of Independent Modules

Hugo's module system resolves each go.mod independently, which let me make a deliberate structural choice: one repository, many modules, each independently importable and versionable. A site that only wants the callout shortcode imports github.com/alex-feel/hugo-artifacts/shortcodes/callout and nothing else; it never pulls the PWA module or its Workbox dependency. That keeps each consumer's dependency graph minimal while letting the whole family share one set of conventions, one CI pipeline, and one place to evolve the style-agnostic contract.

This very website is the proving ground. Every shortcode and the PWA module here are consumed straight from the public modules — the github-repo and hf-space cards on my project pages, the youtube-embed facade on my articles, the callout admonitions throughout, and the offline-capable PWA shell are all the published artifacts, styled entirely by this site's own design tokens. Dogfooding the modules on a real, design-heavy site is what keeps the universality promise honest: if an artifact ever leaked a style, I would feel it here first.

My Role

I designed, built, and maintain Hugo Artifacts end-to-end as a solo open-source project — the monorepo structure and per-module go.mod layout, the style-agnostic output contract, the BEM markup and data-* attribute design for each shortcode, the live-API integrations with their retry and graceful-degradation logic, the privacy-first video facade, the universal callout type system and its blockquote render hook, the PWA module with its Workbox service worker and the vendor-mount resolution recipe for its non-Go upstreams, and the documentation, CI, and release automation for the whole family. It lives on my personal GitHub under an MIT license, and I accept issues and contributions from the wider Hugo community.

It grows directly out of the same open-source instinct behind my st-copy component and my Terraform Cloudflare Zone Module: build the missing primitive once, build it to be genuinely reusable, and give it back to the community rather than rewriting it in every project. If a style-agnostic Hugo component sounds useful for your own site — or if you simply want to talk through the design — the contact page is the best way to reach me.