Hugo PaperMod: a Hugo theme for blogs and portfolios with no JS build step

Who PaperMod is for, and who should look elsewhere

PaperMod is a theme for Hugo, the static site generator. It does not generate sites on its own; it supplies layouts, partials, assets and i18n files that Hugo renders. The README describes it as "a fast, clean, and responsive theme for Hugo" and notes it is based on hugo-paper with additional features and customization options. If you do not already have Hugo installed and a content directory, this theme is not the starting point. If you do, the repository layout tells you what you are getting: layouts/, assets/, i18n/ and theme.toml, with a go.mod declaring module github.com/adityatelange/hugo-PaperMod.

The intended audience is narrow and worth stating plainly. It suits a personal blog, a portfolio, or a small documentation site run by someone comfortable editing TOML and Markdown. It does not suit a team that needs a web-based editor for non-technical authors, because Hugo themes have no admin interface. The README lists no CMS integration and no database, which is the point of the static approach and also its boundary. Nor does it offer comments or form handling; anything interactive is a service you add yourself through a template override, which the wiki documents under Template Overrides.

How the theme is put together: layouts, assets and a Go module

The mechanism is Hugo's own build pipeline, not a separate toolchain. The README states the theme uses Hugo's built-in asset generator with fingerprinting, bundling and minification, and lists "Zero JS build dependencies" with no webpack or Node.js required. Your build command is therefore Hugo itself; there is no npm install step, no lockfile, and no second process to keep alive.

The top-level entries confirm the shape. layouts/ holds the templates Hugo resolves, assets/ holds files that pass through Hugo Pipes for fingerprinting and minification, i18n/ holds translation strings for the multilingual support, and theme.toml declares the theme metadata. Client-side search is powered by Fuse.js according to the feature list, so the search index ships to the browser and is queried there rather than by a server. The theme offers three layout modes, Regular, Home-Info and Profile, documented on the Features wiki page. Those modes change what the home page renders, so the choice is structural rather than cosmetic.

One detail matters for module users. The go.mod declares go 1.16, which is the minimum Go directive for the module file, not the Hugo version you need. The README's badge states a minimum Hugo version of v0.146.0. Treat those as two separate constraints, and note that a theme built on the asset pipeline is exposed to Hugo's template and configuration changes between minor versions.

Installing PaperMod and rendering a first post

The README points to the Installation guide on the GitHub wiki for detailed installation and update instructions, so that page, not the README, is the authoritative source. What the README does establish is that the theme is distributed as a Hugo module: the repository contains a go.mod whose module path is github.com/adityatelange/hugo-PaperMod. The README does not print install commands or a configuration file, so the exact keys and steps come from the wiki rather than from this article.

What the repository does give you is the module identity, which is what a module-based install resolves against, along with the layouts, assets and i18n directories that Hugo reads once the theme is declared. The README also identifies the exampleSite branch as the source for the demo site, and the demo itself is served at adityatelange.github.io/hugo-PaperMod. Building that branch is the most direct way to see a working configuration, because it contains the theme's own settings rather than a description of them.

Once the theme is wired up, a post is ordinary Hugo content: a Markdown file with front matter, rendered by the layouts directory. What you should see is the default Regular mode, a list of posts on the home page and the post at its own URL. If the page renders unstyled, the theme is not being resolved, which points back at the module declaration rather than at your content. Switching to Home-Info or Profile mode is a configuration change described on the Features wiki page, not a template edit.

Where PaperMod stops being the right tool

The honest limitation is that PaperMod is a theme, and a theme can only do what Hugo exposes. Everything the README lists as a feature is a template or an asset: SEO tags, Open Graph, Twitter Cards, Schema.org structured data, breadcrumbs, a table of contents generated from headings, cover images, related posts, social icons and share buttons. None of it is a service. There is no comment backend in the feature list, no form handling, and no server-side search. If your site needs those, you are choosing a third-party service and wiring it in through a template override.

The second limitation is version coupling. The README states a minimum Hugo version of v0.146.0, and the theme depends on Hugo's asset pipeline. Hugo changes template and configuration behaviour between minor versions, so upgrading Hugo without checking the theme is a real failure mode. The README does not document a rollback procedure for a theme upgrade; the wiki's Installation guide is where update instructions live.

The third is release cadence. The most recent tagged release is v8.0, published on 2024-11-03, following v7.0 on 2023-02-12 and v6.0 on 2022-01-14. Commits continue on master, with the last push on 2026-08-02, but the gap between tags is measured in years. If your policy is to track tagged releases only, you will be running a version well behind the default branch.

PaperMod against Blowfish and against a hosted blog

The related searches pair PaperMod with Blowfish, another Hugo theme, so the comparison is worth making concrete. Both are Hugo themes, which means both inherit Hugo's build model and both are configured rather than coded. The difference is in surface area. PaperMod's feature list is deliberately short and grayscale: three layout modes, light and dark themes with automatic switching, multilingual support with a language selector, Fuse.js search, SEO tags, cover images, table of contents, multiple authors, breadcrumbs, archives and taxonomies, code copy buttons, related posts. Blowfish is not described in the repository README, so the only defensible statement is that choosing between them comes down to which one's documented feature set and template structure matches your site. Read both wikis rather than both READMEs.

The other real alternative is not a theme at all. A hosted blogging platform gives you an editor, a database and comments out of the box, and takes away the build step, the Git repository and the ability to diff your site. PaperMod gives you the opposite trade: your content is Markdown in a repository, your build is one Hugo command, and every change is reviewable. If you want the first, no Hugo theme is the answer.

Maintenance cost, licensing and what to verify before adopting

PaperMod is MIT licensed. The practical implication is that you can use, modify and redistribute it, including in commercial work, provided the licence terms are met; the LICENSE file is at the repository root and is the text that governs, not this summary. Nothing here is legal advice, and if you fork the theme and redistribute it you should read the licence yourself.

Maintenance cost breaks into two parts. The theme itself is a dependency you either pin to a tag or track on master. Pinning to v8.0 means you inherit fixes only when you move; tracking master means you inherit changes without a release note. The second part is your own customisation. Because PaperMod is a theme rather than a starter, local changes belong in your site's layouts directory as overrides, which the wiki documents, so a theme update does not overwrite them. If you edit files inside the theme directory instead, every update is a merge.

Before adopting, verify the Hugo version on your machine against the stated minimum of v0.146.0, check the Installation and Features wiki pages for the layout mode you intend to use, and build the exampleSite branch, which the README identifies as the source for the demo site, to see the theme's own configuration rather than guessing at keys. The demo is served from adityatelange.github.io/hugo-PaperMod, which shows the output is a static bundle with no server component.

Editorial conclusion

Adopt PaperMod if you already build with Hugo and want a blog or portfolio you configure in TOML and Markdown rather than in a page builder. Do not adopt it if you need a database-backed CMS, a plugin marketplace, or a theme shipping regular tagged releases; the latest tag is v8.0 from 2024-11-03, and the last push to master was on 2026-08-02. Before you commit, check three things: that your Hugo binary meets the stated minimum of v0.146.0, that the wiki covers the feature you need, and that the exampleSite branch builds the layout mode you want, because PaperMod ships three and picking the wrong one is a configuration problem rather than a bug.

Frequently asked questions

Official sources

1. adityatelange/hugo-PaperMod on GitHub
2. License: MIT
3. Project website
4. README
5. Releases