A bold, distinctive Hugo theme for software developers. Two-column sidebar layout, dark-first with a polished light mode, vivid rust-orange accent, modern type.
- Sticky topbar - search bar with
/keyboard shortcut, theme toggle, full-width reading-progress bar on post pages. - Path-style breadcrumbs - the source-file path is the breadcrumb; each segment links back to its directory.
- Code blocks - labeled header with language, line-wrap toggle, and copy button.
- Static client-side search via Pagefind.
- Smart TOC - sticky collapsible. Scroll-tracked active section highlighted in accent.
- Related posts weighted on tags + series.
- Reading-experience extras - reading progress bar, footnote popovers, image lightbox, GitHub-style callouts.
- Rich content - math passthrough (KaTeX-ready), Mermaid diagrams, image-optimization.
- Hugo extended ≥ 0.158.0 (uses the built-in
css.TailwindCSSpipe). - Node.js (for the npm dependencies - Tailwind CSS v4 CLI, Mermaid and Pagefind).
git submodule add https://github.com/RustyDaemon/rusty-poison.git themes/rusty-poisongit clone https://github.com/RustyDaemon/rusty-poison themes/rusty-poisonIn hugo.toml:
theme = "rusty-poison"You also have to allow Hugo to run the Tailwind CLI. Hugo's default
security.exec.allow list does not include tailwindcss, so css.TailwindCSS
is denied out of the box and the very first build fails with
access denied: "tailwindcss" is not whitelisted in policy "security.exec.allow".
Setting allow replaces the defaults, so repeat the stock entries alongside it:
[security]
[security.exec]
allow = ['^(dart-)?sass$', '^go$', '^git$', '^node$', '^postcss$', '^tailwindcss$']This has to live in the project's own config - Hugo does not merge [security]
from a theme.
The theme declares its own npm dependencies in package.hugo.json. Merge them
into your project's package.json and install:
hugo mod npm pack
npm installhugo mod npm pack writes the merged dependencies to
packages/hugoautogen/package.json and adds a workspaces entry to your root
package.json.
Using pnpm? pnpm ignores the
workspacesfield inpackage.json, so add apnpm-workspace.yamlnext to it beforepnpm install:packages: - packages/hugoautogen
Re-run hugo mod npm pack after upgrading the theme. Then add the scripts you
want:
{
"scripts": {
"dev": "hugo server -D",
"build": "hugo --gc --minify && pagefind --site public",
"search": "pagefind --site public"
}
}npm run dev-hugo serverwith live reload. Search is disabled in dev because the Pagefind index lives underpublic/(regenerated from the built site).npm run build- production build + Pagefind index.- For full local search testing:
npm run build && npx serve public.
A minimal hugo.toml:
baseURL = "https://example.com/"
locale = "en-us"
title = "Your Site"
theme = "rusty-poison"
enableEmoji = true
pagination.pagerSize = 10
[params]
brand = "Your Site"
brand_image = "/images/logo.png" # optional, lives in /static
description = "Notes from..." # default meta description
tagline = "// short tagline" # appears under the website name in the sidebar
favicon = "/favicon.png"
showDarkLight = true # show topbar theme toggle
hideToc = false
front_page_content = ["posts"] # which sections show on the home page
menu = [
{Name = "posts", URL = "/posts/", HasChildren = false},
{Name = "series", URL = "/series/", HasChildren = false},
{Name = "tags", URL = "/tags/", HasChildren = false},
# {Name = "projects", URL = "/projects/", HasChildren = false},
]
github_url = "https://github.com/you"
mastodon_url = "https://mastodon.social/@you"
# bluesky_url, x_url, linkedin_url, youtube_url, discord_url, instagram_url,
# facebook_url, email_url, twitter_url - all optional
rss_icon = true
rss_section = "posts"
[taxonomies]
series = "series"
tags = "tags"
[related]
threshold = 80
includeNewer = true
toLower = false
[[related.indices]]
name = "tags"
weight = 100
[[related.indices]]
name = "series"
weight = 80
[[related.indices]]
name = "date"
weight = 10
[markup]
[markup.tableOfContents]
startLevel = 2
endLevel = 4
ordered = false
[markup.highlight]
codeFences = true
noClasses = false
style = "monokai" # cosmetic when noClasses=false; theme ships its own colors
tabWidth = 2
[markup.goldmark]
[markup.goldmark.renderer]
unsafe = true
[markup.goldmark.extensions]
[markup.goldmark.extensions.passthrough]
enable = true
[markup.goldmark.extensions.passthrough.delimiters]
block = [['\[', '\]'], ['$$', '$$']]
inline = [['\(', '\)']]
[security]
# Required - Hugo's default exec allowlist has no tailwindcss entry.
[security.exec]
allow = ['^(dart-)?sass$', '^go$', '^git$', '^node$', '^postcss$', '^tailwindcss$']title = "Post title"
date = 2026-05-03
description = "Optional lede line under the title."
tags = ["go", "systems"]
series = "Some Series" # custom taxonomy, renders the series list
hideToc = false # opt out of the TOC for this post
featuredImage = "/images/myimage.png" # optional hero image
project = false # if true, the post is treated as a project The accent and surface tokens live in
assets/css/main.css under the @theme block. Edit them there - they propagate to the entire UI through CSS custom properties.
Use GitHub-style alert syntax inside markdown:
> [!NOTE]
> Useful information that the user should know, even when skimming content.
> [!TIP]
> Helpful advice for doing things better or more easily.
> [!WARNING]
> Urgent info that needs immediate user attention.
> [!CAUTION]
> Negative potential consequences of an action.
> [!IMPORTANT]
> Crucial information necessary for users to succeed.Goldmark passthrough is enabled, so $inline$, \(inline\), $$display$$,
and \[display\] math is preserved in the output. Add a client-side
KaTeX/MathJax loader (or render server-side via transform.ToMath in a
shortcode) if you want the math rendered.
Use a fenced code block with mermaid:
```mermaid
graph LR
A --> B
B --> C
```The Mermaid runtime is loaded lazily and only when a pre.mermaid element
is present on the page.
{{</* details summary="Hidden content" */>}}
Click to reveal.
{{</* /details */>}}
Licensed under Apache-2.0.
Fonts and other packages are licensed separately, see their respective documentation for details.