papermod-themes — Hugo Blog Template

SHA-256: c09a7ddfc928b132985390711fd8045a4350c77d5fe28840740693d967074f78

2026-10-12T09:31:00.642Z

# papermod-themes

Three drop-in redesigns for Hugo blogs running [PaperModX](https://github.com/reorx/hugo-PaperModX/) (and mostly stock [PaperMod](https://github.com/adityatelange/hugo-PaperMod) — see [notes](#notes)).

No theme surgery, no forks: each design is a set of files you copy into your site. PaperMod(X) concatenates anything in `assets/css/extended/` after its own styles, and site-level `layouts/` override the theme's — that's the whole mechanism.

**Live demos** (on [alex-jacobs.com](https://alex-jacobs.com/), switchable via URL param):

| design | vibe | demo |
|---|---|---|
| **agent session** | Claude Code / OpenCode terminal aesthetic — warm dark, orange accent, tool-call post list, session composer | [?design=claude](https://alex-jacobs.com/?design=claude) |
| **docs minimal** | Geist/Vercel-style monochrome minimalism — hairlines, tight type, zero chrome | [?design=geist](https://alex-jacobs.com/?design=geist) |
| **the editor** | Tokyo Night IDE — editor tab bar, file-explorer post list, VS Code status bar | [?design=ide](https://alex-jacobs.com/?design=ide) |

## agent session

![agent session](screenshots/agent-session.png)

The blog as a Claude Code session. Welcome-box hero with pixel monogram, `Read(title)` tool-call post entries, terminal-window single posts, blinking composer caret, animated *Thinking…* shimmer. Warm gruvbox syntax theme. Best in dark mode, ships with a warm cream light mode too.

[Install →](agent-session/)

## docs minimal

![docs minimal](screenshots/docs-minimal.png)

Monochrome docs aesthetic. Geist + Geist Mono, uppercase micro-labels, post index as hairline rows with tabular dates, GitHub light/dark syntax themes. Built for `defaultTheme: auto` — both modes are first-class.

[Install →](docs-minimal/)

## the editor

![the editor](screenshots/the-editor.png)

The blog as an IDE. Editor tab bar (`alex-jacobs.md`, `projects.yaml`), `welcome.md` hero rendered as line-numbered markdown source, posts as a file-explorer tree, fixed status bar (`git:(main)` · `Ln 1, Col 1` · `UTF-8` · `Markdown` · `✓ Prettier`). Tokyo Night + Tokyo Night Light syntax themes.

[Install →](the-editor/)

## Install (any design)

1. Pick a design folder above.
2. Copy its `assets/` and `layouts/` trees into your Hugo site root (merge, don't replace your whole folders).
3. Recommended config tweaks:
   ```yaml
   params:
     defaultTheme: dark   # for agent session / the editor; docs minimal prefers auto
   pygmentsUseClasses: true   # required — the syntax themes are class-based chroma
   ```
4. `hugo server` and enjoy.

Uninstall = delete the files you copied. Nothing else is touched.

## Notes

- **Syntax highlighting** is class-based chroma. Keep `pygmentsUseClasses: true` (or `markup.highlight.noClasses: false`). The palettes drop into `assets/css/lib/chroma-{dark,light}.css`, which PaperModX's `highlight.scss` imports automatically. On stock PaperMod, chroma classes also work — you may need to ship your own chroma CSS wiring depending on your setup.
- **Hugo extended** required (SCSS). Tested on Hugo 0.101+.
- Everything degrades gracefully: no JS required, and stock features (search, ToC, archives, tags, covers, theme toggle) keep working.
- Each design supports both dark and light mode via the PaperMod(X) theme toggle.

## Credits

Made by [Alex Jacobs](https://alex-jacobs.com/). The terminal components in *agent session* were inspired by [brainless](https://brainless.swerdlow.dev/). Tokyo Night palette by [folke](https://github.com/folke/tokyonight.nvim).

If you use one of these, a link back to [alex-jacobs.com](https://alex-jacobs.com/) or this repo somewhere on your site is appreciated.

## License

[MIT](LICENSE)