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:
params:
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:
params:
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.
menu:
main:
- name: "@Author"
url: "https://reorx.com"
params:
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-widthintheme-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 
