Rusty Poison

Rusty Poison is a Hugo theme for software developers, built with a two-column sidebar layout, a dark-first palette with a light mode, and a rust-orange accent. It requires Hugo extended 0.158.0 or newer and relies on npm for Tailwind CSS v4, Mermaid, and Pagefind.

What is Rusty Poison?

Rusty Poison is a Hugo theme aimed at developer blogs and note-taking sites. It takes standard Hugo content and config (hugo.toml plus markdown front matter) as input and outputs a static site whose styling is compiled at build time through Hugo's built-in css.TailwindCSS pipe. The theme is published by RustyDaemon on GitHub and licensed under Apache-2.0.

What makes Rusty Poison stand out?

• Sidebar layout — a two-column design with a sticky topbar containing a search bar, / keyboard shortcut, and theme toggle.
• Pagefind search — fully static client-side search; the index lives under public/ and is regenerated from the built site, so search is disabled during hugo server dev runs.
• Path-style breadcrumbs — the source-file path acts as the breadcrumb, with each segment linking to its directory.
• Code blocks — labeled header showing the language, a line-wrap toggle, and a copy button.
• Smart TOC — sticky and collapsible, with the active section highlighted in the accent color as you scroll.
• Reading extras — reading-progress bar, footnote popovers, image lightbox, and GitHub-style callouts ([!NOTE], [!TIP], [!WARNING], [!CAUTION], [!IMPORTANT]).
• Rich content support — KaTeX-ready math passthrough via Goldmark delimiters, lazily loaded Mermaid diagrams rendered only when a pre.mermaid element exists, a details shortcode, and image optimization.
• Tailwind CSS v4 — colors and surface tokens live in assets/css/main.css under an @theme block and propagate through CSS custom properties.
• Related posts — weighted on tags and series, configured in [related] with tags at weight 100 and series at 80.

Who is it for?

• Developer bloggers: publish technical posts with syntax-highlighted, copyable code blocks and scroll-tracked tables of contents.
• Writers of long-form notes: organize posts into a custom series taxonomy and get tag- and series-weighted related-post links.
• Documenters: use breadcrumbs tied to source-file paths and collapsible details sections to structure reference material.

How does it work?

Install the theme as a git submodule or clone into themes/, set theme = "rusty-poison" in hugo.toml, then add tailwindcss to security.exec.allow in the project config — Hugo's default allowlist omits it and the first build fails otherwise. Run hugo mod npm pack to merge the theme's package.hugo.json dependencies, then npm install. Use npm run dev for live reload or npm run build, which runs hugo --gc --minify followed by pagefind --site public. pnpm users must add a pnpm-workspace.yaml listing packages/hugoautogen.

FAQ

Is Rusty Poison free?

Yes. Rusty Poison is licensed under Apache-2.0 and distributed freely from its GitHub repository. Fonts and other bundled packages carry their own separate licenses, documented in their respective packages.

Why does the first build fail with an access-denied error?

Hugo's default security.exec.allow list does not include tailwindcss, so the css.TailwindCSS pipe is denied. Add ^tailwindcss$ to security.exec.allow in your project's own config — Hugo does not merge [security] from a theme — and repeat the stock entries, since setting allow replaces the defaults.

Does search work during local development?

No. The Pagefind index is generated from the built site under public/, so it is unavailable while running hugo server. To test search locally, run npm run build and then serve the public directory.