Paper is a minimal Hugo theme for blogs that turns a standard Hugo site configuration into a fast, clean reading experience with dark mode, comment integrations, and social links.
What is Paper?
Paper is a Hugo theme designed for personal blogs and content sites. It takes a Hugo site's content and configuration and renders it as a lightweight, customizable blog theme. The theme is maintained by nanxiaobei and distributed under the MIT License, with a live demo at hugo-paper.vercel.app.
Key Features
- Color schemes — choose from linen, wheat, gray, or light via a single
colorsetting in the config file. - Dark mode — automatic or manual dark mode with an option for a monochrome dark-mode icon.
- Comment integrations — Disqus, giscus, and Graph Comment are supported through config options.
- Social icons — header links for Twitter, GitHub, Instagram, LinkedIn, Mastodon, Threads, Bluesky, and RSS.
- Math typesetting — enable KaTeX globally or per page with the
mathparameter, with an option to serve KaTeX locally instead of from a CDN. - RTL support — set
direction = "rtl"for right-to-left languages. - Customizable profile — home page avatar, name, and bio can be set via config values.
- Front matter controls — disable comments or enable math on individual posts.
Who is it for?
- Bloggers who want a clean, fast Hugo theme without a heavy front-end framework.
- Technical writers who need KaTeX math rendering for documentation or tutorials.
- Multilingual authors who publish in RTL languages and need proper layout direction.
- Self-hosters who prefer a theme installable as a git submodule or Hugo module.
What can you do with Paper?
- Personal bloggers: publish markdown posts and get a fast, accessible site with dark mode and social link icons.
- Developers: extend the theme by editing Hugo templates and config files, since the theme is open source under MIT.
- Site owners: integrate Disqus, giscus, or Graph Comment to enable reader discussions without building your own comment system.
How does Paper work?
Install the theme by adding the repository as a git submodule or as a Hugo module, then set theme = "paper" in your site config. Customize behavior through the [params] section of config.toml or hugo.toml. The theme is versioned (current version 6.30) and listed on Hugo Themes and Product Hunt.
Pros and cons
- Fast and lightweight — the theme uses no heavy JavaScript dependencies beyond optional highlight.js and KaTeX.
- Easy install — two official installation methods: git submodule or Hugo module.
- Limited built-in page types — it focuses on blog content rather than offering landing pages, portfolios, or e-commerce templates.
FAQ
Is Paper free?
Yes, Paper is open source under the MIT License, so it can be used freely for personal or commercial projects.
Does Paper support dark mode?
Paper includes dark mode and allows you to choose from four background color styles: linen, wheat, gray, and light. You can also display a monochrome dark-mode icon.
Can I use Disqus with Paper?
Yes, set the Disqus shortname in the [services.disqus] config section. Alternatively, giscus and Graph Comment are supported.
How do I install Paper?
You can add it as a git submodule with git submodule add https://github.com/nanxiaobei/hugo-paper themes/paper or as a Hugo module by adding the module import to your config.
Does Paper support math equations?
Yes, enable KaTeX by setting math = true in the config or in a page's front matter. You can also host KaTeX locally by setting localKatex = true.
