PaperModX: an enhanced fork of the popular PaperMod theme

Hi community, I want to share my recent work on creating a better Hugo theme based on the popular PaperMod, it’s called PaperModX, check it out: PaperModX

Why not PaperMod?

I was intended to use PaperMod at first, after digging deeper into it, I found many flaws I wish to imporve:

  • Out-of-date technologies

    PaperMod is based on Paper which is created 3 years ago, the fundation is old and the author didn’t intend to upgrade them. For example CSS files are splited and not well organized, concanation process is hard-coded in html, this could be improved by using modern tools like SCSS or PostCSS. Code highlighting is implemented with highlight.js, though Chroma is supported, it is not the first-class citizen and dirty hacks are spreaded across the code. There’s a lot of things to be upgraded.

  • Lack of code quality and engineering

    In PaperMod’s code I noticed that many are copy-paste without abstraction and modulization, especially when handling feature flag with JavaScript. This makes the code hard to read and maintain, which becomes a burden to add new features and support the community issues agilely. Another example is that the svg icons are treated as partial html code not data, this makes it impossible for the users to add their own icons in the site data, leading to the situation that many PR in PaperMod are just for adding icons.

  • Incomplete features

    Though PaperMod brings a lot of features, some of them are incomplete and I’m not very optimistic about the development progress. For example the side ToC feature request has been around for a year, but there not plan to support it, even some well made PR is ignored.

Why fork?

Despite these problems, PaperMod is still the very best theme in the Hugo community, it is sophisticated, feature rich, and well documented. So it’s better to build upon it rather than making a new one from the ground up.

What makes PaperModX different?

Currently, PaperModX has implements the following features and changes. you can take a look at the docs and demo on this site: PaperModX New Features | PaperModX

Table of Contents (ToC) floating on the side

By adding config:

  TocSide: 'left'  # or 'right'

ToC will float on the left/right side of the page.
You can take a look at how 'right' feels like in “Installation | Update”
The ToC box is responsive, it only shows on the side when minimum screen size is 1440px.

InstantClick integration

By adding config:

  EnableInstantClick: true

InstantClick will be enabled,
making navigation behaves like Single Page Application.

Note that /search pages are omitted from InstantClick
to prevent conflicts from search’s JavaScript,
this may be changed in the future after refactoring those scripts.

Another thing to notice is smooth scrolling will be disabled
if InstantClick is enabled, because they both listen click
event on every <a> tags. IMO smooth scrolling is not very useful
so it has to give way to InstantCllick.

Give links an accent color.

Though PaperModX is designed to be minimal, accent color is still essential.
It’s a good way to show personality and make your site feels more delightful.

The default color is a purple vibe,
you can customize the colors of link, link underline and their hover variants
by override the following css variables in assets/css/extended/custom.css of your site.

:root {
  --link-color: var(--primary);
  --link-hover-color: #573eaa;
  --link-underline-shadow: 0 1px 0 var(--link-color);
  --link-hover-underline-color: #573eaa;
  --link-hover-underline-shadow: 0 2px 0 var(--link-hover-underline-color);

Customize pagniator size

In section pages, if you want the paginator size be different from the
global config,
you can add paginate in the frontmatter to customize.

paginate: 10

Menus external link

You can add external: true to a menu item’s params to mark it as an external link,
this will add a small icon to the end, and make the link open in new tab when clicked.

    - name: "@Author"
      url: ""
        external: true

Highlight code with Chroma, no bullshit

PaperMod uses highlight.js to highlight code blocks.
In PaperModX, we use Chroma which is the recommended way in Hugo’s
official docs,
thus changing theme is easily supported.

By default the themes are github for light and dracula for dark,
you can change it by adding chroma-light.css and chroma-dark.css
in site’s assets/css/lib directory.

Social icons from Simple Icons

Add social icons with -simple suffix from Simple Icons.

Available icons:

  • github-simple
  • rss-simple
  • telegram-simple
  • twitter-simple
  • pinboard-simple

The icons are moved from layouts/partials/svg.html to data/svg.toml,
makes it easier to maintain, it’s now possible to have an index page
to show all the icons.

Opinionated UI enhancements

  • Distinguish home page width and post page width, post page is wider
    (800px) for better readability, you can change it by --post-width in theme-vars.css.
  • Menu links are always bold, this feels more consistent when clicking around. Active links have deeper color.

Future plans

I’m going to release the first stable version of PaperModX after the 1.0 milestone is finished:

  • [ ] Enhance code copy button
  • [ ] Use SCSS instead of CSS
  • [ ] Allow using icons from site’s data dir
  • [ ] Enhance search page

Before the release, you can still use this theme by just adding it as a submodule to the themes/ directory, I make the best effort to keep PaperModX compatible with PaperMod while implementing new features and refactoring code, and since I’m a fulltime digital normad, you can expect a quick response from me during my day time (UTC+8).

Thanks for reading, have fun blogging :slight_smile:


This is amazing and by far my favorite theme. I wish there were an option to make it fit “magazine “ style sites! Any plans for that?

Thanks for your appreciation. I plan to enhance the layout for posts that have many images, but I’m not sure if that is what you need, can you give me an example for the “magazine” style sites?

Obviously it doesn’t have to be that complicated. Just a simple featured image slider at the top, then a. Column of posts with thumbnail. Then the post should show that thumbnail with a caption inside the post with the news post.

I’m afraid this is not in the scope of PaperModX’s design philosophy. PaperModX is for text-based sites to have a clear and readability-friendly look. But you could implement your own home page by adding layouts/index.html in your site directory, it will completely replace the home page PaperModX provides. That’s why Hugo theme is flexible, isn’t it?

BTW I know Hashnode has a layout like that, could possibly be a choice


Would it be possible to add image wallpapers to PaperModX? It seems very few Hugo themes have wallpapers, and it would looks quite nice, make it a bit less plain. Could even display different wallpapers on light/dark mode? The theme I’m using, Dream, is one of the few themes with this. I’m trying to figure out how to add wallpapers to Diary for a friend

@reorx The social icons are not displaying in Safari mobile. Ive tried both in profile mode and blog layout but they don’t work. It works on all other browsers. Is anyone else facing this issue? What could be a potential fix?
For reference, this is my site.

They’re SVGs; perhaps mobile Safari does not support SVG? Ideally should have PNG fallbacks; I’ve faced such issues while crafting EPUBs before. Try something like:

<p style="text-align: center;">
	<object data="../Images/social_logo.svg" type="image/svg+xml" width="96" height="69">
		<img src="../Images/social_logo.png" alt="Leaf-shaped divider"/>

Might not necessarily work, as a lot of Hugo themes use some sort of font or icon provider service to provide service icons. Dream (the theme I use) uses a web font, which I localised in my fork (i.e. it loads locally rather than from a CDN, which I recommend for privacy and reliability)

1 Like

It does: "svg" | Can I use... Support tables for HTML5, CSS3, etc


1 Like

We need a navbar toggle in smaller screen display, like mobile view. The author of PaperMod theme won’t give it to us. He has a weird personality, I think he should fix it. lol

1 Like

Makes sense, I will test with a fall back option.

@jhvanderschee I just tested it again on my iPhone 12, running iOS 15.6. It does not seem to work.
This is what appears on screen.

Dark icons on a dark background?

The theme switches to light icons reliably when on dark mode, so I don’t think that’s the case.
For comparison, this is how it appears on mobile Firefox,

It doesn’t appear to be a case where icons are invisible (but present). Had that been the case, you’d be able to click them & see them on hover.

Some sort of ad blocker? Some also block social links (feature, not a bug).

1 Like

You are spot on!
Turns out it was ‘Adblocker - Social’ that was active on Safari, blocking those links. I did not know this was a feature lol, until now!

Thank you, much appreciated!

1 Like

I’ve been using PaperMod theme for over one year. I like its simplicity. And I’m glad to see a more powerful & configurable theme of PaperMod!

Well done!
When I have time I will give it a try.

1 Like