Onion

Onion is an experimental Hugo theme for static site generators that produces a privacy-focused, multilingual blog with zero external dependencies and no build pipeline.

What is Onion?

Onion is a Hugo theme (minimum Hugo 0.154.0, Extended recommended) created by Heracles Papatheodorou and previewed live at heracl.es. It takes standard Hugo content — posts, pages, custom post types like preformatted — and outputs a static website with automatic table of contents, Tufte-style sidenotes, archives grouped by year, and full-content RSS and JSON feeds. The theme is distributed on GitHub at github.com/arty2/onion and installs as a Hugo Module, Git submodule, or Git subtree.

Key Features

• Zero dependencies — No pre-processors, no JavaScript frameworks, and no external dependencies; all scripts are self-hosted inside the theme and there is no build step.
• Multilingual first — English and Greek are bundled, with OS-preference-driven light/dark schemes and bundled webfonts (Alegreya serif default, Alegreya Sans, Fantasque Sans Mono).
• Articles listing shortcodes — articles-list offers display classes like cluster, preformatted, no-tags, and no-text; articles-filter provides client-side, multi-select tag filtering with a noscript post-count fallback.
• Forge content shortcode — forge-content fetches READMEs or any file from public GitHub, GitLab, Forgejo, or Codeberg repos at build time and inlines rendered Markdown after neutralising Hugo shortcodes and stripping dangerous HTML/attributes.
• Responsive images — Hero and listing images use responsive srcset, WebP conversion (Hugo Extended), fetchpriority="high" on the LCP image, and URL fragment modifiers like #blend, #screen, #multiply, and #shadow.
• Theming with CSS custom properties — Five colour themes (default, peach, retro, gray, blue), light/dark schemes, and serif/sans/mono font modifiers are all toggled via the params.theme string.
• Privacy-friendly extras — No cookies, self-hosted assets, Open Graph and schema.org metadata, Speculation Rules prerender, microformats markup, and a gadget column with return-to-top and theme toggle.
• Extensible front-matter — Theme-specific keys like cover, show_toc, license, rating, and publication sit alongside standard Hugo front-matter, with compatibility for PaperMod, Hextra, Stack, Congo/Blowfish, and Anatole parameter names.

Who is it for?

Onion suits Hugo users who want a typography-focused blog theme without any JavaScript build tooling. It targets personal bloggers, writers, and multilingual site owners (English and Greek are built in), as well as developers who appreciate a theme with progressive enhancement and graceful degradation in older browsers. Its overlap with popular Hugo themes' front-matter makes it a low-friction migration target for sites coming from PaperMod, Hextra, Stack, Congo/Blowfish, or Anatole.

What can you do with Onion?

• Personal bloggers: Publish articles with automatic TOC, sidenotes, archives by year, and full-content RSS/JSON feeds.
• Multilingual sites: Run English and Greek content with OS-preference-based dark mode and bundled multilingual webfonts.
• Open-source maintainers: Embed READMEs from GitHub, GitLab, Forgejo, or Codeberg into documentation pages at build time using forge-content, with security filtering for untrusted repositories.
• Visual storytellers: Create image galleries, set hero/cover images with responsive srcset, and apply blend/shadow effects via URL fragments.

How does Onion work?

Onion installs as a Hugo Module (recommended, pinned to a minor version), a Git submodule, or a Git subtree, then activates by setting theme = "onion" in your site's config. A fully-annotated config.default.toml is provided; the bundled exampleSite runs with hugo server and CI builds it against two Hugo versions on every push.

Pros and cons

Pros: Zero external dependencies, no build pipeline, strong privacy posture (no cookies, self-hosted scripts), graceful degradation without JavaScript, and flexible theming via CSS custom properties. Cons: The theme is experimental — the README warns that breaking changes are routine between untagged commits and recommends using a tagged release for production. It also only supports lazy menus (no nesting) and older browsers don't get feature parity.

Pricing

Onion is free and open source under the MIT License.

Alternatives

• PaperMod — a popular Hugo theme with similar parameter names that onion intentionally matches.
• Hextra — a Hugo theme with a different visual approach.
• Stack — a Hugo theme mentioned in onion's migration guidance.
• Congo / Blowfish — Hugo themes with comparable configuration keys.
• Anatole — a minimal Hugo theme with overlapping front-matter conventions.

FAQ

Is Onion free?

Yes, Onion is released under the MIT License and can be used for personal or commercial projects without cost.

What Hugo version does Onion require?

Onion requires Hugo 0.154.0 or newer. Hugo Extended is strongly recommended because WebP conversion and some image features depend on it.

Does Onion work without JavaScript?

Yes. Core functionality does not depend on JavaScript; every built-in script has a noscript fallback or simply no-ops. For example, the article filter degrades to showing post counts when JavaScript is disabled.

How do I migrate from another Hugo theme?

Onion's parameter names deliberately overlap with PaperMod, Hextra, Stack, Congo/Blowfish, and Anatole. Most keys can be pasted across; the README's migration table maps differences like params.ShowToc to params.showToc and params.defaultTheme to a params.theme class string.

Can I use Onion for a site with multiple languages?

Yes, Onion is multilingual first and ships with English and Greek translation bundles. It also respects OS preferences for light/dark colour scheme and reduced motion.