Public multi-module Hugo monorepo for reusable artifacts -- themes, shortcode libraries, asset libraries, utility modules, and other components shared across any number of unrelated Hugo sites.
The guiding principle is universality: every artifact is built to drop into any site and be styled to fit it, never to impose a look. Components ship DATA and semantic markup -- not design decisions -- so each consuming site owns its own presentation. See Design Principles for what that means and why.
Each artifact lives in its own subdirectory with an independent go.mod, making it independently importable and versionable.
These artifacts are meant to be reused across many unrelated sites, so they avoid baking in any single site's look. The contract differs slightly by artifact kind, but the spirit is shared: ship what is stable and reusable (structure, data, behavior, accessibility) and leave what legitimately varies per site (visual presentation) to the consumer.
- Style-agnostic by default. The shortcode and component libraries (everything under
shortcodes/) emit semantic BEM markup and ship zero CSS -- no.scss, no.css, no inline<style>, no hardcoded colors, and no dark-mode rules. The consuming site owns all visual styling (typically a site-sideassets/scss/_<name>.scss). - Cross the styling boundary with data, not styles. Components expose objective values as
data-*attributes (for exampledata-callout-type,data-video-id) and, where a value must reach CSS, as a CSS custom-property name the site defines (for examplestyle="--callout-tone: var(--callout-tone-danger)"-- a pointer to a token, never a literal color). Class hooks follow BEM: the block is the component name, modifiers are<name>--<modifier>, and elements are<name>__<part>. - Icons are the one shipped visual, and they stay restyleable. They render as inline SVGs using
currentColorand1emsizing, so they inherit the consumer's text color and font size and can be restyled entirely from the site. - Universal, not opinionated. Because no design decisions are shipped, one component drops into any number of sites and each styles it however it needs -- no specificity wars, no styles to override, and the site's own theme and dark-mode tokens flow straight through.
The payoff: you can build a design of any complexity on top of these artifacts without fighting styles they impose, because they impose none. For the authoring rules behind this contract, see the shortcode module conventions and CONTRIBUTING.md.
Importable Hugo modules live under modules/. Each module ships its own README.md with installation, configuration, and consumption instructions.
Universal SEO module: one {{ partial "seo/head.html" . }} call emits the complete head surface (title, meta description, canonical, robots, hreflang, Open Graph, Twitter Cards, site verification, feed discovery) plus Google-eligible JSON-LD structured data (WebSite, Organization, WebPage, BreadcrumbList, Article/BlogPosting/NewsArticle, Product, ProfilePage, SoftwareApplication, VideoObject) cross-linked by @id. Reuses Hugo-native front-matter fields, adds a clean seo.* contract on top, validates strictly, and degrades gracefully. See modules/seo/README.md.
Universal sharing bar: one {{ partial "social-share/share.html" . }} call (or the social-share shortcode) renders style-agnostic BEM markup with plain share-intent links for up to 28 networks -- X, Facebook, LinkedIn, Reddit, Bluesky, Threads, Mastodon, Telegram, WhatsApp, VK, and more -- plus JavaScript-revealed Web Share, copy-link, and print buttons. Zero CSS, zero third-party contact before a deliberate click, real-text accessible names, full i18n, a four-tier configuration cascade, and consumer-extensible network registry. See modules/social-share/README.md.
Universal client-side site search: a per-language JSON index emitted at build time through a custom output format, searched entirely in the visitor's browser by a vendored MiniSearch engine with English and Russian stemming, typo tolerance, prefix matching, and BM25 field-weighted ranking. Three surfaces share one core -- a dedicated search page (works without JavaScript), a command-palette modal (Ctrl/Cmd+K), and an inline dropdown -- with Web Worker index construction, serialized-index caching, APG-pattern accessibility, full i18n (en/ru), zero CSS, and zero external services. The index dates itself with the build's own timestamp, taken from the agent-readiness module when a site runs both so every dated document of one deploy carries the same string, and computed here when it does not. See modules/search/README.md.
Universal build-time image module: one {{ partial "images/image.html" (dict "page" . "src" "..." "alt" "...") }} call (or the image shortcode, or plain Markdown ![...]() via the shipped render hook) emits style-agnostic BEM <picture> markup with width-descriptor srcsets that never upscale, WebP plus original-format fallback (AVIF opt-in on Hugo 0.163.0+), guaranteed width/height for zero layout shift, strict alt discipline, figure/caption/credit surfaces, JS-free dominant-color and blur placeholders, light/dark variant pairs for both OS-preference and class-based togglers, art direction, gallery rendering, and a PhotoSwipe-compatible lightbox enablement contract. Zero CSS, zero JavaScript, a four-tier configuration cascade under params.img, and graceful degradation on every unprocessable source. See modules/images/README.md.
Accessible, APG-conformant image carousel: style-agnostic BEM markup and zero CSS, with an optional self-authored JavaScript enhancement (subresource-integrity-pinned, no third-party dependency) that layers in previous/next controls, an optional slide picker, and current-slide state synchronization over a functional no-JS baseline -- keyboard operability comes from the controls being native buttons, reachable and activatable without any script; touch/swipe is native browser scrolling, not a JS-implemented gesture; and there is no autoplay, by design, because auto-rotating content is a WCAG 2.2.2 failure mode this module refuses to ship. Composes with modules/images when both are imported (each slide is a full images/image.html render), and ships a Markdown twin variant for the site's agent-facing representations. See modules/carousel/README.md.
Universal agent-readiness module: the agent-facing representations of a site your HTML already describes, all driven by one shared page-selection filter so they can never disagree -- a generated robots.txt with a 21-token AI-crawler registry and a Content-Signal declaration, per-page Markdown twins built from .RenderShortcodes with a duplicate-key-safe YAML front matter, a compact llms.txt link index beside a complete /llms-index.txt one -- two documents from ONE page walk, so a per-section selection principle can bound the file an agent reads first without putting anything out of reach, and a section that principle narrowed opens with a line saying how many pages it is showing and where the rest are, so a reader cannot mistake an omission for a fact about the site -- an aggregated /about.md facts document that is complete by construction rather than truncated, and a /.well-known/agent-skills/ discovery index whose SHA-256 digests are computed from the exact bytes it republishes -- single SKILL.md bodies, whole archives, and the declared supporting files it republishes beside a multi-file skill's SKILL.md so their relative references resolve. The twins, both link indexes, /about.md and the skills index each carry one build stamp -- a single RFC 3339 timestamp per build, byte-identical across every document and every language, and exposed through a public partial so a consuming site can stamp its own surfaces, and the search module its index, with the same string. It answers what a digest cannot: a hash says whether two copies differ, never which one is newer. Zero CSS, zero JavaScript, zero visual surface; a four-tier configuration cascade under params.agent; graceful degradation on every misconfiguration and every failed remote fetch. See modules/agent-readiness/README.md.
Universal "Copy page" widget: one {{ partial "copy-page/menu.html" . }} call (or the copy-page shortcode) renders a Mintlify-style split button for any page that publishes a Markdown representation -- a JavaScript-revealed primary half that copies the page's Markdown to the clipboard, plus a native <details> disclosure menu of rows (view as Markdown, open llms.txt, hand the page to ChatGPT, Claude, Perplexity, Grok, or Google AI Studio). Style-agnostic BEM markup, zero CSS, zero third-party contact before a deliberate click, a Safari-safe layered clipboard flow, full i18n (en/ru), a four-tier configuration cascade under params.copy_page, and a consumer-extensible row registry. See modules/copy-page/README.md.
Universal build-time Open Graph card generator: one {{ partial "og-image/card.html" . }} call returns a composed social card for the page as an image resource, or nothing when the page is one this generator has no template for. A card is a site-supplied background raster normalized to the canvas, any number of overlays, and any number of text slots drawing the page's own words or the site's canonical facts -- title, description, section, date, a front-matter param, a data-file value, a literal -- laid out by a text engine that measures and wraps against a configured box, walks a bounded size ladder when the words do not fit, and truncates with an ellipsis only at the floor. The module ships no templates, no fonts and no colors: the consuming site supplies the backdrop, the coordinates and the type, so every card is that site's design rather than this module's. PNG, JPEG or WebP output, a four-tier configuration cascade under params.ogcard, one card per page and language memoized across the repeated calls a page receives, and graceful degradation throughout -- an unreadable font, an unusable background or a failed compose is one deduplicated warning and a page that keeps whatever image it would otherwise have had, never a broken build. Composes with modules/seo: point [params.seo] image_partial at og-image/card.html and the composed card becomes the page's og:image, with real dimensions and a matching JSON-LD image node, while a page the generator declines falls through to the site's default image. It also ships a standalone {{ partial "og-image/meta.html" . }} renderer for sites that do not use the seo module. See modules/og-image/README.md.
Consumer-facing Progressive Web App module: web app manifest, RealFaviconGenerator icon set, Workbox-powered service worker, install prompt, and push subscription wiring. Composes with modules/url-retirement: the two URLs it publishes that no walk of a site's pages can reach -- the service worker and the offline page -- are registered with that module's URL manifest when a site imports both, so a deployment check covers them without the site naming either by hand. See modules/pwa/README.md.
Vendor-mount companion that exposes github.com/GoogleChrome/workbox v7.4.1 source files as Hugo assets for js.Build. Imported transitively by modules/pwa, which records it at a real commit pseudo-version, so consumers neither import nor require it directly -- see modules/workbox/README.md.
Vendor-mount companion that exposes github.com/jakearchibald/idb v8.0.3 source files as Hugo assets. Imported transitively by modules/workbox (and therefore by modules/pwa), which records it at a real commit pseudo-version, so consumers neither import nor require it directly -- see modules/idb/README.md.
Universal URL-retirement module: publishes /_redirects -- the host redirect map read by Cloudflare Pages, GitLab Pages and Netlify -- containing the site's own hand-written rules verbatim followed by one real 301 redirect per page alias, one per paginated list and one for the redirect Hugo runs between the site root and its default language, so a retired URL -- including the /blog/page/1/ Hugo stops publishing once its pagination alias is switched off, and the /en/ or / a multilingual site retires -- becomes a server-side redirect instead of a meta-refresh stub, plus a per-language /url-manifest.txt listing every URL the build publishes -- every page crossed with its output formats, plus paginated list pages, whatever a module registers for what it published outside the page graph, and whatever a format's owner answers when the manifest asks what else that format wrote, none of which a sitemap contains -- so a deployment check can diff what production serves against what the build produces instead of diffing a sitemap, which is a filtered subset. Style-agnostic, zero CSS, zero JavaScript, a two-tier configuration cascade under params.url_retirement, and graceful degradation on every misconfiguration -- the one fatal case is an alias containing whitespace, which would silently corrupt the file format. See modules/url-retirement/README.md.
Reusable Hugo shortcode modules live under shortcodes/. Every one is style-agnostic -- semantic BEM markup, data-* attributes, and zero CSS (see Design Principles) -- so you style it to fit your site. Each ships its own README.md with installation, usage, parameters, and styling guidance.
Renders a GitHub repository link in one of five display variants (inline, card, stats, lang, hero) with API-driven metadata, a last-updated label at calendar-day granularity (relative, absolute date, or omitted -- a per-call choice), header-aware retries, and graceful degradation. See shortcodes/github-repo/README.md.
Renders a GitHub person-profile widget for presenting one's own activity and achievements: contribution totals, the contribution calendar (heatmap), per-organization contribution rollups, external-collaboration footprint, byte-weighted language shares, reviews given, and optional identity, pinned, membership, and social sections. Ten composable sections behind three presets (compact, card, full), one GraphQL request per profile by default, opt-in all-time history, streaks, merged-PR count, and a transparent activity score, with header-aware retries and graceful degradation. Requires HUGO_GITHUB_TOKEN (the GraphQL API has no anonymous tier). See shortcodes/github-profile/README.md.
Renders a Hugging Face Space link in one of five display variants (inline, card, wide, stats, hero) with Hub API-driven metadata (emoji, SDK, hardware, likes, gradient colors, a last-modified label at calendar-day granularity with a relative / absolute-date / omitted per-call choice), header-aware retries, and graceful degradation. The sibling of shortcodes/github-repo. See shortcodes/hf-space/README.md.
Renders an arXiv.org paper reference in one of six display variants (inline, card, wide, stats, hero, cite) from the arXiv Atom API, with optional Semantic Scholar (one-sentence TLDR, resolved venue, citation count) and Hugging Face Papers (AI summary, keyword chips, code-repo badge, upvotes) enrichment, header-aware retries, and graceful degradation. Resolves subject codes to human-readable names from a shipped taxonomy map, renders the revision date at calendar-day granularity (relative, absolute date, or omitted -- a per-call choice), and stamps volatile counts with a data-arxiv-metrics-asof freshness hook. Consuming sites must allow-list application/atom+xml in security.http.mediaTypes (one line, documented in the module README). See shortcodes/arxiv-paper/README.md.
Privacy-first YouTube facade: 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. Supports id/url parsing (all common shapes plus ?t= offsets), playlists, an explicit local poster override, arbitrary player-parameter passthrough, responsive same-origin <picture> posters, and a no-JavaScript fallback link. See shortcodes/youtube-embed/README.md.
Universal, unstyled accordion built on the native <details> / <summary> elements: paired {{< accordion >}} / {{< accordion-item >}} shortcodes for Markdown plus a public accordion/list.html partial for layouts, with optional single-open groups, opt-in heading semantics, and per-item deep-link anchors. Ships zero JavaScript, zero CSS, and zero ARIA -- the browser carries the toggle, the keyboard interaction, and the state semantics. See shortcodes/accordion/README.md.
Universal, unstyled paired admonition shortcode ({{< callout "type" >}}...{{< /callout >}}) with fifteen first-class types, true-synonym aliases, arbitrary custom-type passthrough, native <details> collapsibility, opt-in ARIA, and overridable icons. Also ships a blockquote render hook so GitHub-style > [!NOTE] alerts render as the same markup. See shortcodes/callout/README.md.
The examples/ directory contains standalone reference implementations that pair with modules/pwa. They are not importable Hugo modules -- they are runnable push-notification backends meant to be deployed to a separate platform. See examples/README.md for the catalog and examples/QUICKSTART.md for a 5-minute end-to-end walkthrough.
Contributions are welcome. See CONTRIBUTING.md for development setup, coding conventions, the Markdown one-line-per-paragraph rule, tagging and release conventions, and pull request guidelines.
Have a question, found a bug, or want to request a feature? Open an issue using one of the issue templates -- they prompt you for the details needed to help quickly.
Report security vulnerabilities privately via GitHub Security Advisories rather than opening a public issue. See SECURITY.md for the full policy.
Released under the MIT License.