Skip to content
Get packs

Guide · Open source

How to use hugo-PaperMod: install and set up the Hugo theme

Updated · written with AI from the project's own documentation and checked against our catalogue data

hugo-PaperMod is a theme for Hugo, a tool that turns text and Markdown files into a website. It gives a blog or portfolio a fast, clean, responsive layout with light and dark modes, search and built-in SEO metadata. This guide explains what the theme needs, how to add it to a Hugo site and where to look when you want to customize it.

PaperModadityatelange/hugo-PaperMod · ★ 14k · MIT

Quick start

  1. 1Check Hugo version. Confirm that Hugo v0.158.0 or later is installed on your machine.
  2. 2Create or open a Hugo site. Work inside the root folder of the Hugo site you want to style.
  3. 3Clone the theme. Run the git clone command from the README to place the theme in themes/PaperMod.
  4. 4Enable the theme. Set the theme in your Hugo configuration, following the Installation wiki page.
  5. 5Configure site options. Use the Variables and Icons wiki pages to set site title, social links and language options.
  6. 6Customize with overrides. Place changed templates in your own site folder using the Template_Overrides guide rather than editing the theme.
  7. 7Preview and publish. Run Hugo locally to preview the site, then build and publish it.

What hugo-PaperMod is and who it suits

PaperMod is a set of templates and styles that runs inside Hugo. It is aimed at people who want a polished site without writing much front-end code. It is a good fit for bloggers who already use Hugo, simple minimal portfolio sites, and multilingual sites that need a built-in language selector.

  • It only runs inside Hugo, so you need Hugo to use it.
  • The README centers on its existing layouts and customization options, so a heavily custom design may be a poor match.
  • It needs no webpack, Node.js or other JavaScript build tooling.

Check the prerequisites before you install

The README lists one prerequisite: Hugo v0.158.0 or later. Check your installed version before you start, and upgrade Hugo if it is older.

Install hugo-PaperMod by cloning it into your themes folder

Install the theme by cloning the repository into the themes directory of your Hugo site. The README gives this command, which uses a shallow clone to fetch only the latest state of the repository. The README points to the GitHub wiki's Installation page for detailed installation and update instructions.

git clone https://github.com/adityatelange/hugo-PaperMod themes/PaperMod --depth=1

Enable the theme and configure the site

Once the theme is in the themes folder, tell Hugo to use it. The README does not spell out the configuration keys in the truncated source, so follow the Installation and FAQs wiki pages linked from the README for the exact settings. The wiki also documents the template variables and the social icon configuration.

  • Read the Installation wiki page for the setup steps.
  • Use the Variables wiki page to find the template variables you can set.
  • Use the Icons wiki page to configure social links and share buttons.

Customize layouts without forking the theme

If you want to change the look, the README recommends the template override approach described in the wiki's Template_Overrides page. This is a guide to customizing templates without forking, so your changes stay separate from the theme files.

  • Layout modes include Regular, Home-Info and Profile.
  • Light and dark mode switches automatically based on browser preference and offers a manual toggle.
  • Table of contents is generated from the heading structure of each post.

Use the built-in features: search, SEO and code blocks

The theme includes client-side search powered by Fuse.js. It adds Open Graph, Twitter Cards and Schema.org structured data out of the box. Code blocks get Chroma syntax highlighting and copy buttons.

  • Search runs in the browser through Fuse.js.
  • Open Graph, Twitter Cards and Schema.org data are included by default.
  • Cover images, multiple authors, breadcrumbs, archives, taxonomies and related post suggestions are also built in.

What people use it for

  • A personal blog written in Markdown with dark mode and search.
  • A minimal portfolio with a profile layout.
  • A multilingual site that uses the built-in language selector.
  • A documentation-style or article site that benefits from a table of contents and related posts.

Frequently asked questions

Is hugo-PaperMod free to use?

The project is licensed under the MIT licence, as stated in the repository. Check the LICENSE file in the repository for the full terms.

What do I need to run hugo-PaperMod?

You need Hugo v0.158.0 or later. The README lists no other prerequisite, and it needs no webpack, Node.js or other JavaScript build tooling.

How do I install hugo-PaperMod?

Clone the repository into the themes folder of your Hugo site with git clone https://github.com/adityatelange/hugo-PaperMod themes/PaperMod --depth=1. The GitHub wiki Installation page has detailed steps.

Does hugo-PaperMod support multiple languages?

Yes. The README says it includes a built-in language selector for multilingual sites.

How do I customize hugo-PaperMod without breaking updates?

The README points to the Template_Overrides wiki page, which describes customizing templates without forking the theme.

How does hugo-PaperMod compare to Ananke or Congo?

The README lists Ananke, Hugo Stack, Congo and Terminal as comparable projects. It does not compare them in detail, so test the themes on a sample site to see which layout and features suit you.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

hugo-PaperMod suits people who already use Hugo, or are willing to learn it, and want a fast, clean blog or portfolio with search, dark mode and SEO built in. Pick something else if you do not want to use Hugo, need a heavily custom design, or want a visual site builder with no command-line use.

Install options & downloads